Informazioni di riferimento per le descrizioni dei controlli preliminari per Aurora MySQL

Livello di controllo preliminare: errore

Problemi segnalati dal comando check table x for upgrade per lo schema mysql

Prima di iniziare l’aggiornamento ad Aurora MySQL versione 3, check table for upgrade viene eseguito su ogni tabella dello schema mysql dell’istanza database. Il comando check table for upgrade esamina le tabelle per individuare eventuali problemi che potrebbero verificarsi durante l’aggiornamento a una versione più recente di MySQL. L’esecuzione di questo comando prima di tentare un aggiornamento può aiutare a identificare e risolvere eventuali incompatibilità in anticipo, rendendo più agevole l’effettivo processo di aggiornamento.

Questo comando esegue diversi controlli su ogni tabella, come i seguenti:

Per ulteriori informazioni, consulta CHECK TABLE statement nella documentazione di MySQL.

Output di esempio:

{
  "id": "checkTableMysqlSchema",
  "title": "Issues reported by 'check table x for upgrade' command for mysql schema.",
  "status": "OK",
  "detectedProblems": []
}

L’output di questo controllo preliminare dipende dall’errore riscontrato e dal momento in cui si verifica l’errore, poiché check table for upgrade esegue più controlli.

Se riscontri errori con questo controllo preliminare, apri un caso con il Supporto AWS per richiedere che l’incoerenza dei metadati venga risolta. In alternativa, puoi tentare nuovamente l’aggiornamento eseguendo un dump logico, quindi effettuando il ripristino su un nuovo cluster di database Aurora MySQL versione 3.

Livello di controllo preliminare: errore

Riferimenti circolari alle directory nei percorsi dei file di dati del tablespace

A partire da MySQL 8.0.17, la clausola CREATE TABLESPACE ... ADD DATAFILE non consente più i riferimenti circolari alle directory. Per evitare problemi di aggiornamento, rimuovi tutti i riferimenti circolari alle directory dai percorsi dei file di dati del tablespace prima di eseguire l’aggiornamento ad Aurora MySQL versione 3.

Output di esempio:

{
  "id": "circularDirectory",
  "title": "Circular directory references in tablespace data file paths",
  "status": "OK",
  "description": "Error: Following tablespaces contain circular directory references (e.g. the reference '/../') in data file paths which as of MySQL 8.0.17 are not permitted by the CREATE TABLESPACE ... ADD DATAFILE clause. An exception to the restriction exists on Linux, where a circular directory reference is permitted if the preceding directory is a symbolic link. To avoid upgrade issues, remove any circular directory references from tablespace data file paths before upgrading.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-innodb-changes",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "ts2",
        "description": "circular reference in datafile path: '/home/ec2-user/dbdata/mysql_5_7_44/../ts2.ibd'",
        "dbObjectType": "Tablespace"
      }
  ]
}

Se ricevi questo errore, crea nuovamente le tabelle utilizzando un tablespace file-per-table. Utilizza i percorsi di file predefiniti per tutti i tablespace e le definizioni delle tabelle.

Una volta creati nuovamente i tablespace, il controllo preliminare viene superato e l’aggiornamento può procedere.

{
  "id": "circularDirectoryCheck",
  "title": "Circular directory references in tablespace data file paths",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Colonne che non possono avere valori predefiniti

Prima di MySQL 8.0.13, le colonne BLOB, TEXT, GEOMETRY e JSON non possono avere valori predefiniti. Rimuovi tutte le clausole predefinite in queste colonne prima dell’aggiornamento ad Aurora MySQL versione 3. Per ulteriori informazioni sulle modifiche alla gestione predefinita per questi tipi di dati, consulta Data type default values nella documentazione di MySQL.

Output di esempio:

{
  "id": "columnsWhichCannotHaveDefaultsCheck",
  "title": "Columns which cannot have default values",
  "status": "OK",
  "description": "Error: The following columns are defined as either BLOB, TEXT, GEOMETRY or JSON and have a default value set. These data types cannot have default values in MySQL versions prior to 8.0.13, while starting with 8.0.13, the default value must be specified as an expression. In order to fix this issue, please use the ALTER TABLE ... ALTER COLUMN ... DROP DEFAULT statement.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/data-type-defaults.html#data-type-defaults-explicit",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.test_blob_default.geo_col",
        "description": "geometry"
      }
  ]
},

Il controllo preliminare restituisce un errore perché la colonna geo_col della tabella test.test_blob_default utilizza un tipo di dati BLOB, TEXT, GEOMETRY, o JSON con un valore predefinito specificato.

Guardando la definizione della tabella, possiamo vedere che la colonna geo_col è definita come geo_col geometry NOT NULL default ''.

mysql> show create table test_blob_default\G
*************************** 1. row ***************************
       Table: test_blob_default
Create Table: CREATE TABLE `test_blob_default` (
  `geo_col` geometry NOT NULL DEFAULT ''
) ENGINE=InnoDB DEFAULT CHARSET=latin1

Rimuovi questa clausola predefinita per consentire il superamento del controllo preliminare.

mysql> ALTER TABLE test_blob_default modify COLUMN geo_col geometry NOT NULL;
Query OK, 0 rows affected (0.02 sec)
Records: 0  Duplicates: 0  Warnings: 0

mysql> show create table test_blob_default\G
*************************** 1. row ***************************
       Table: test_blob_default
Create Table: CREATE TABLE `test_blob_default` (
  `geo_col` geometry NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=latin1
1 row in set (0.00 sec)

Il controllo preliminare viene superato e puoi tentare nuovamente di eseguire l’aggiornamento.

{
  "id": "columnsWhichCannotHaveDefaultsCheck",
  "title": "Columns which cannot have default values",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Utilizzo di parole chiave obsolete nella definizione

MySQL 8.0 ha rimosso la cache delle query. Di conseguenza, è stata rimossa una parte della sintassi SQL specifica della cache delle query. Se uno qualsiasi degli oggetti del database contiene le parole chiave QUERY CACHE, SQL_CACHE o SQL_NO_CACHE, viene restituito un errore di controllo preliminare. Per risolvere il problema, crea nuovamente gli oggetti rimuovendo le parole chiave menzionate.

Output di esempio:

{
  "id": "depreciatedSyntaxCheck",
  "title": "Usage of depreciated keywords in definition",
  "status": "OK",
  "description": "Error: The following DB objects contain keywords like 'QUERY CACHE', 'SQL_CACHE', 'SQL_NO_CACHE' which are not supported in major version 8.0. It is recommended to drop these DB objects or rebuild without any of the above keywords before upgrade.",
  "detectedProblems": [
      {
"level": "Error",
"dbObject": "test.no_query_cache_check",
"description": "PROCEDURE uses depreciated words in definition"
      }
  ]
}

Il controllo preliminare segnala che la stored procedure test.no_query_cache_check utilizza una delle parole chiave rimosse. Guardando la definizione della procedura, possiamo vedere che utilizza SQL_NO_CACHE.

mysql> show create procedure test.no_query_cache_check\G
*************************** 1. row ***************************
           Procedure: no_query_cache_check
            sql_mode:
    Create Procedure: CREATE DEFINER=`reinvent`@`%` PROCEDURE `no_query_cache_check`()
BEGIN
    SELECT SQL_NO_CACHE k from sbtest1 where id > 10 and id < 20 group by k asc;
END
character_set_client: utf8mb4
collation_connection: utf8mb4_0900_ai_ci
  Database Collation: latin1_swedish_ci
1 row in set (0.00 sec)

Rimuovi la parola chiave.

mysql> drop procedure test.no_query_cache_check;
Query OK, 0 rows affected (0.01 sec)

mysql> delimiter //

mysql> CREATE DEFINER=`reinvent`@`%` PROCEDURE `no_query_cache_check`() BEGIN     SELECT k from sbtest1 where id > 10 and id < 20 group by k asc; END//
Query OK, 0 rows affected (0.00 sec)

mysql> delimiter ;

Dopo aver rimosso la parola chiave, il controllo preliminare viene completato correttamente.

{
  "id": "depreciatedSyntaxCheck",
  "title": "Usage of depreciated keywords in definition",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Tabelle riconosciute da InnoDB che appartengono a un motore diverso

In modo analogo a schemaInconsistencyCheck, questo controllo preliminare verifica che i metadati delle tabelle in MySQL siano coerenti prima di procedere con l’aggiornamento.

Se riscontri errori con questo controllo preliminare, apri un caso con il Supporto AWS per richiedere che l’incoerenza dei metadati venga risolta. In alternativa, puoi tentare nuovamente l’aggiornamento eseguendo un dump logico, quindi effettuando il ripristino su un nuovo cluster di database Aurora MySQL versione 3.

Output di esempio:

{
  "id": "engineMixupCheck",
  "title": "Tables recognized by InnoDB that belong to a different engine",
  "status": "OK",
  "description": "Error: Following tables are recognized by InnoDB engine while the SQL layer believes they belong to a different engine. Such situation may happen when one removes InnoDB table files manually from the disk and creates e.g. a MyISAM table with the same name.\n\nA possible way to solve this situation is to e.g. in case of MyISAM table:\n\n1. Rename the MyISAM table to a temporary name (RENAME TABLE).\n2. Create some dummy InnoDB table (its definition does not need to match), then copy (copy, not move) and rename the dummy .frm and .ibd files to the orphan name using OS file commands.\n3. The orphan table can be then dropped (DROP TABLE), as well as the dummy table.\n4. Finally the MyISAM table can be renamed back to its original name.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "mysql.general_log_backup",
        "description": "recognized by the InnoDB engine but belongs to CSV"
      }
  ]
}

Livello di controllo preliminare: errore

Definizioni delle colonne ENUM e SET che contengono elementi con più di 255 caratteri

Le tabelle e le stored procedure non devono contenere elementi colonna ENUM o SET con più di 255 caratteri o 1020 byte. Prima di MySQL 8.0, la lunghezza massima combinata era di 64K, ma la versione 8.0 limita i singoli elementi a 255 caratteri o 1020 byte (con supporto per i multibyte). Se si verifica un errore di controllo preliminare per enumSetElementLengthCheck, modifica tutti gli elementi che superano i nuovi limiti prima di tentare di eseguire nuovamente l’aggiornamento.

Output di esempio:

{
  "id": "enumSetElementLengthCheck",
  "title": "ENUM/SET column definitions containing elements longer than 255 characters",
  "status": "OK",
  "description": "Error: The following columns are defined as either ENUM or SET and contain at least one element longer that 255 characters. They need to be altered so that all elements fit into the 255 characters limit.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/string-type-overview.html",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.large_set.s",
        "description": "SET contains element longer than 255 characters"
      }
  ]
},

Il controllo preliminare segnala un errore perché la colonna s della tabella test.large_set contiene un elemento SET con più di 255 caratteri.

Dopo aver ridotto le dimensioni SET di questa colonna, il controllo preliminare viene eseguito e l’aggiornamento può continuare.

{
  "id": "enumSetElementLenghtCheck",
  "title": "ENUM/SET column definitions containing elements longer than 255 characters",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Nomi di vincoli di chiave esterna con più di 64 caratteri

In MySQL, la lunghezza degli identificatori è limitata a 64 caratteri, come indicato nella documentazione di MySQL. A causa dei problemi identificati per cui la lunghezza delle chiavi esterne poteva essere uguale o superiore a questo valore, con conseguenti errori di aggiornamento, è stato implementato questo controllo preliminare. Se si verificano errori con questo controllo preliminare, è necessario modificare o rinominare il vincolo interessato in modo che sia inferiore a 64 caratteri prima di tentare di eseguire nuovamente l’aggiornamento.

Output di esempio:

{
  "id": "foreignKeyLength",
  "title": "Foreign key constraint names longer than 64 characters",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Tutti i nomi dei trigger in un database devono essere univoci.

A causa delle modifiche nell’implementazione del dizionario dei dati, MySQL 8.0 non supporta i trigger con distinzione tra maiuscole e minuscole all’interno di un database. Questo controllo preliminare verifica che il cluster di database non disponga di uno o più database contenenti trigger duplicati. Per ulteriori informazioni, consulta Identifier case sensitivity nella documentazione di MySQL.

Output di esempio:

{
  "id": "getDuplicateTriggers",
  "title": "MySQL pre-checks that all trigger names in a database are unique or not.",
  "status": "OK",
  "description": "Error: You have one or more database containing duplicate triggers. Mysql 8.0 does not support case sensitive triggers within a database https://dev.mysql.com/doc/refman/8.0/en/identifier-case-sensitivity.html. To upgrade to MySQL 8.0, drop the triggers with case-insensitive duplicate names and recreate with distinct names.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test",
        "description": "before_insert_product"
      },
      {
        "level": "Error",
        "dbObject": "test",
        "description": "before_insert_PRODUCT"
      }
  ]
}

Il controllo preliminare segnala un errore per cui il cluster di database ha due trigger con lo stesso nome, ma che utilizzano lettere maiuscole e minuscole diverse: test.before_insert_product e test.before_insert_PRODUCT.

Prima dell’aggiornamento, rinomina i trigger o eliminali e creali di nuovo con un nuovo nome.

Dopo la ridenominazione di test.before_insert_PRODUCT in test.before_insert_product_2, il controllo preliminare ha esito positivo.

{
  "id": "getDuplicateTriggers",
  "title": "MySQL pre-checks that all trigger names in a database are unique or not.",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

La colonna definer per mysql.event non può essere nulla o vuota.

L’attributo DEFINER specifica l’account MySQL che possiede una definizione di oggetto memorizzato, come un trigger, una stored procedure o un evento. Questo attributo è particolarmente utile in situazioni in cui si desidera controllare il contesto di sicurezza in cui viene eseguito l’oggetto memorizzato. Quando si crea un oggetto memorizzato, se non è specificato un DEFINER, l’impostazione predefinita è l’utente che ha creato l’oggetto.

Quando si esegue l’aggiornamento a MySQL 8.0, non è possibile avere oggetti memorizzati che abbiano un definer null o vuoto nel dizionario dei dati di MySQL. Se si dispone di tali oggetti memorizzati, viene generato un errore di controllo preliminare. È necessario correggerlo prima di procedere con l’aggiornamento.

Esempio di errore:

{
  "id": "getEventsWithNullDefiner",
  "title": "The definer column for mysql.event cannot be null or blank.",
  "status": "OK",
  "description": "Error: Set definer column in mysql.event to a valid non-null definer.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.get_version",
        "description": "Set definer for event get_version in Schema test"
      }
  ]
}

Il controllo preliminare restituisce un errore per l’evento test.get_version perché ha un definer null.

Per risolvere questo problema puoi controllare la definizione dell’evento. Come puoi vedere, il definer è null o vuoto.

mysql> select db,name,definer from mysql.event where name='get_version';
+------+-------------+---------+
| db   | name        | definer |
+------+-------------+---------+
| test | get_version |         |
+------+-------------+---------+
1 row in set (0.00 sec)

Elimina o crea nuovamente l’evento con un definer valido.

mysql> drop event test.get_version;
Query OK, 0 rows affected (0.00 sec)

mysql> DELIMITER ;
mysql> delimiter $$
mysql> CREATE EVENT get_version
    ->     ON SCHEDULE
    ->       EVERY 1 DAY
    ->     DO
    ->      ///DO SOMETHING //
    -> $$
Query OK, 0 rows affected (0.01 sec)

mysql> DELIMITER ;

mysql> select db,name,definer from mysql.event where name='get_version';
+------+-------------+------------+
| db   | name        | definer    |
+------+-------------+------------+
| test | get_version | reinvent@% |
+------+-------------+------------+
1 row in set (0.00 sec)

Ora il controllo preliminare viene superato.

{
  "id": "getEventsWithNullDefiner",
  "title": "The definer column for mysql.event cannot be null or blank.",
  "status": "OK",
  "detectedProblems": []},

Livello di controllo preliminare: errore

Mancata corrispondenza delle definizioni delle colonne tra il dizionario dei dati InnoDB e la definizione effettiva della tabella

In modo analogo a schemaInconsistencyCheck, questo controllo preliminare verifica che i metadati delle tabelle in MySQL siano coerenti prima di procedere con l’aggiornamento. In questo caso, il controllo preliminare verifica che le definizioni delle colonne corrispondano tra il dizionario dei dati InnoDB e la definizione della tabella MySQL. Se viene rilevata una mancata corrispondenza, l’aggiornamento non procede.

Se riscontri errori con questo controllo preliminare, apri un caso con il Supporto AWS per richiedere che l’incoerenza dei metadati venga risolta. In alternativa, puoi tentare nuovamente l’aggiornamento eseguendo un dump logico, quindi effettuando il ripristino su un nuovo cluster di database Aurora MySQL versione 3.

Output di esempio:

{
  "id": "getMismatchedMetadata",
  "title": "Column definition mismatch between InnoDB Data Dictionary and actual table definition.",
  "status": "OK",
  "description": "Error: Your database has mismatched metadata. The upgrade to mysql 8.0 will not succeed until this is fixed.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.mismatchTable",
        "description": "Table `test/mismatchTable` column names mismatch with InnoDb dictionary column names: iD <> id"
      }
  ]
}

Il controllo preliminare segnala una mancata corrispondenza nei metadati per la colonna id della tabella test.mismatchTable. In particolare, i metadati MySQL hanno il nome della colonna iD, mentre InnoDB ha il nome id.

Livello di controllo preliminare: errore

La colonna definer per information_schema.triggers non può essere null o vuota.

Il controllo preliminare verifica che il database non abbia trigger definiti con definer null o vuoti. Per ulteriori informazioni sui requisiti del definer per gli oggetti memorizzati, consulta getEventsWithNullDefiner.

Output di esempio:

{
  "id": "getTriggersWithNullDefiner",
  "title": "The definer column for information_schema.triggers cannot be null or blank.",
  "status": "OK",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.example_trigger",
        "description": "Set definer for trigger example_trigger in Schema test"
      }
  ]
}

Il controllo preliminare restituisce un errore perché il trigger example_trigger nello schema test ha un definer null. Per risolvere questo problema, correggi il definer creando nuovamente il trigger con un utente valido oppure elimina il trigger. Per ulteriori informazioni, consulta l’esempio in getEventsWithNullDefiner.

Livello di controllo preliminare: errore

Tutti i nomi di database o tabelle devono avere lettere minuscole quando il parametro lower_case_table_names è impostato su 1.

Prima di MySQL 8.0, i nomi dei database, i nomi delle tabelle e altri oggetti corrispondevano ai file nella directory dei dati, come i metadati basati su file (.frm). La variabile di sistema lower_case_table_names consente di controllare il modo in cui il server gestisce la distinzione tra maiuscole e minuscole degli identificatori per gli oggetti del database e l’archiviazione di tali oggetti di metadati. Questo parametro può essere modificato su un server già inizializzato dopo un riavvio.

Tuttavia, in MySQL 8.0, sebbene questo parametro controlli ancora il modo in cui il server gestisce la distinzione tra maiuscole e minuscole degli identificatori, non può essere modificato dopo l’inizializzazione del dizionario dei dati. Quando si aggiorna o si crea un database MySQL 8.0, il valore impostato per lower_case_table_names al primo avvio del dizionario dei dati su MySQL viene utilizzato per tutta la durata del database. Questa restrizione è stata messa in atto nell’ambito dell’implementazione di Atomic Data Dictionary, in cui viene eseguita la migrazione degli oggetti del database dai metadati basati su file alle tabelle InnoDB interne dello schema mysql.

Per ulteriori informazioni, consulta Data dictionary changes nella documentazione di MySQL.

Per evitare problemi durante l’aggiornamento mentre si aggiornano i metadati basati su file al nuovo Atomic Data Dictionary, questo controllo preliminare verifica che quando lower_case_table_names = 1 tutte le tabelle vengano memorizzate su disco in lettere minuscole. In caso contrario, viene restituito un errore di controllo preliminare ed è necessario correggere i metadati prima di procedere con l’aggiornamento.

Output di esempio:

{
  "id": "getValueOfVariablelower_case_table_names",
  "title": "MySQL pre-checks that all database or table names are lowercase when the lower_case_table_names parameter is set to 1.",
  "status": "OK",
  "description": "Error: You have one or more databases or tables with uppercase letters in the names, but the lower_case_table_names parameter is set to 1. To upgrade to MySQL 8.0, either change all database or table names to lowercase, or set the parameter to 0.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.TEST",
        "description": "Table test.TEST contains one or more capital letters in name while lower_case_table_names = 1"
      }
  ]
}

Viene restituito un errore perché la tabella test.TEST contiene lettere maiuscole, ma lower_case_table_names è impostato su 1.

Per risolvere questo problema, è possibile rinominare la tabella utilizzando lettere minuscole o modificare il parametro lower_case_table_names nel cluster di database prima di iniziare l’aggiornamento.

Livello di controllo preliminare: errore

Utilizzo della sintassi GROUP BY ASC/DESC rimossa

A partire da MySQL 8.0.13, la sintassi ASC o DESC obsoleta per le clausole GROUP BY è stata rimossa. Le query che si basano sull’ordinamento GROUP BY potrebbero ora produrre risultati diversi. Per ottenere un ordinamento specifico, utilizza invece una clausola ORDER BY. Se nel database sono presenti oggetti che utilizzano questa sintassi, è necessario crearli nuovamente utilizzando una clausola ORDER BY prima di tentare di eseguire di nuovo l’aggiornamento. Per ulteriori informazioni, consulta SQL changes nella documentazione di MySQL.

Output di esempio:

{
  "id": "groupbyAscSyntaxCheck",
  "title": "Usage of removed GROUP BY ASC/DESC syntax",
  "status": "OK",
  "description": "Error: The following DB objects use removed GROUP BY ASC/DESC syntax. They need to be altered so that ASC/DESC keyword is removed from GROUP BY clause and placed in appropriate ORDER BY clause.",
  "documentationLink": "https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-13.html#mysqld-8-0-13-sql-syntax",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.groupbyasc",
        "description": "PROCEDURE uses removed GROUP BY ASC syntax",
        "dbObjectType": "Routine"
      }
  ]
}

Livello di controllo preliminare: errore

Verifica la presenza di una sintassi .<table> obsoleta utilizzata nelle routine.

In MySQL 8.0, le routine non possono più contenere la sintassi dell’identificatore obsoleta (\".<table>\"). Se alcune routine o trigger memorizzati contengono tali identificatori, l’aggiornamento non riesce. Ad esempio, il seguente riferimento .dot_table non è più consentito:

mysql> show create procedure incorrect_procedure\G
*************************** 1. row ***************************
           Procedure: incorrect_procedure
            sql_mode:
    Create Procedure: CREATE DEFINER=`reinvent`@`%` PROCEDURE `incorrect_procedure`()
BEGIN delete FROM .dot_table; select * from .dot_table where 1=1; END
character_set_client: utf8mb4
collation_connection: utf8mb4_0900_ai_ci
  Database Collation: latin1_swedish_ci
1 row in set (0.00 sec)

Dopo aver creato nuovamente le routine e i trigger per utilizzare la sintassi dell’identificatore e l’escape corretti, il controllo preliminare viene superato e l’aggiornamento può procedere. Per ulteriori informazioni, consulta Schema object names nella documentazione di MySQL.

Output di esempio:

{
  "id": "mysqlEmptyDotTableSyntaxCheck",
  "title": "Check for deprecated '.<table>' syntax used in routines.",
  "status": "OK",
  "description": "Error: The following routines contain identifiers in deprecated identifier syntax (\".<table>\"), and should be corrected before upgrade:\n",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.incorrect_procedure",
        "description": " routine body contains deprecated identifiers."
      }
  ]
}

Il controllo preliminare restituisce un errore per la routine incorrect_procedure nel database test perché contiene una sintassi obsoleta.

Dopo aver corretto la routine, il controllo preliminare ha esito positivo ed è possibile tentare di eseguire nuovamente l’aggiornamento.

Livello di controllo preliminare: errore

Verifica la presenza di indici troppo grandi per funzionare su versioni di MySQL successive alla 5.7

Per i formati di riga compatti o ridondanti, non dovrebbe essere possibile creare un indice con un prefisso con più di 767 byte. Tuttavia, prima della versione 5.7.35 di MySQL questo era possibile. Per ulteriori informazioni, consulta le note di rilascio di MySQL 5.7.35.

Tutti gli indici interessati da questo bug diventeranno inaccessibili dopo l’aggiornamento a MySQL 8.0. Questo controllo preliminare identifica gli indici che causano l’errore, che devono essere creati nuovamente prima che l’aggiornamento possa procedere.

 {
  "id": "mysqlIndexTooLargeCheck",
  "title": "Check for indexes that are too large to work on higher versions of MySQL Server than 5.7",
  "status": "OK",
  "description": "Error: The following indexes ware made too large for their format in an older version of MySQL (older than 5.7.34). Normally those indexes within tables with compact or redundant row formats shouldn't be larger than 767 bytes. To fix this problem those indexes should be dropped before upgrading or those tables will be inaccessible.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.table_with_large_idx",
        "description": "IDX_2"
      }
  ]
}

Il controllo preliminare restituisce un errore perché la tabella test.table_with_large_idx contiene un indice su una tabella che utilizza un formato di riga compatto o ridondante con più di 767 byte. Queste tabelle diventerebbero inaccessibili dopo l’aggiornamento a MySQL 8.0. Prima di procedere con l’aggiornamento, esegui una delle seguenti operazioni:

In questo esempio, creiamo nuovamente la tabella per risolvere l’errore di controllo preliminare. Prima di ricostruire la tabella, assicurati che innodb_file_format sia impostato su Barracuda e che innodb_default_row_format sia impostato su dynamic. Queste sono le impostazioni predefinite in MySQL 5.7. Per ulteriori informazioni, consulta InnoDB row formats e InnoDB file-format management nella documentazione di MySQL.

mysql > select @@innodb_file_format,@@innodb_default_row_format;
+----------------------+-----------------------------+
| @@innodb_file_format | @@innodb_default_row_format |
+----------------------+-----------------------------+
| Barracuda            | dynamic                     |
+----------------------+-----------------------------+
1 row in set (0.00 sec)

mysql> optimize table table_with_large_idx;
+---------------------------+----------+----------+-------------------------------------------------------------------+
| Table                     | Op       | Msg_type | Msg_text                                                          |
+---------------------------+----------+----------+-------------------------------------------------------------------+
| test.table_with_large_idx | optimize | note     | Table does not support optimize, doing recreate + analyze instead |
| test.table_with_large_idx | optimize | status   | OK                                                                |
+---------------------------+----------+----------+-------------------------------------------------------------------+
2 rows in set (0.02 sec)

# Verify FILE_FORMAT and ROW_FORMAT
mysql>  select * from information_schema.innodb_sys_tables where name like 'test/table_with_large_idx';
+----------+---------------------------+------+--------+-------+-------------+------------+---------------+------------+
| TABLE_ID | NAME                      | FLAG | N_COLS | SPACE | FILE_FORMAT | ROW_FORMAT | ZIP_PAGE_SIZE | SPACE_TYPE |
+----------+---------------------------+------+--------+-------+-------------+------------+---------------+------------+
|       43 | test/table_with_large_idx |   33 |      4 |    26 | Barracuda   | Dynamic    |             0 | Single     |
+----------+---------------------------+------+--------+-------+-------------+------------+---------------+------------+
1 row in set (0.00 sec)

Una volta creata nuovamente la tabella, il controllo preliminare viene superato e l’aggiornamento può procedere.

{
  "id": "mysqlIndexTooLargeCheck",
  "title": "Check for indexes that are too large to work on higher versions of MySQL Server than 5.7",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Verifica la presenza di nomi di tabelle e schemi non validi utilizzati in MySQL 5.7

Durante la migrazione al nuovo dizionario dei dati in MySQL 8.0, l’istanza database in uso non può contenere schemi o tabelle con il prefisso #mysql50#. Se esistono oggetti di questo tipo, l’aggiornamento non riesce. Per risolvere questo problema, esegui mysqlcheck sugli schemi e sulle tabelle restituiti.

Output di esempio:

{
  "id": "mysqlInvalid57NamesCheck",
  "title": "Check for invalid table names and schema names used in 5.7",
  "status": "OK",
  "description": "The following tables and/or schemas have invalid names. In order to fix them use the mysqlcheck utility as follows:\n\n  $ mysqlcheck --check-upgrade --all-databases\n  $ mysqlcheck --fix-db-names --fix-table-names --all-databases\n\nOR via mysql client, for eg:\n\n  ALTER DATABASE `#mysql50#lost+found` UPGRADE DATA DIRECTORY NAME;",
  "documentationLink": "https://dev.mysql.com/doc/refman/5.7/en/identifier-mapping.html https://dev.mysql.com/doc/refman/5.7/en/alter-database.html https://dev.mysql.com/doc/refman/8.0/en/mysql-nutshell.html#mysql-nutshell-removals",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "#mysql50#fix_db_names",
        "description": "Schema name"
      }
  ]
}

Il controllo preliminare segnala che lo schema #mysql50#fix_db_names ha un nome non valido.

Una volta corretto il nome dello schema, il controllo preliminare viene superato e l’aggiornamento può procedere.

{
  "id": "mysqlInvalid57NamesCheck",
  "title": "Check for invalid table names and schema names used in 5.7",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Verifica la presenza di routine orfane in 5.7

Durante la migrazione al nuovo dizionario dei dati in MySQL 8.0, se nel database sono presenti stored procedure in cui lo schema non esiste più, l’aggiornamento non riesce. Questo controllo preliminare verifica che tutti gli schemi a cui si fa riferimento nelle stored procedure sull’istanza database esistano ancora. Per consentire il proseguimento dell’aggiornamento, elimina queste stored procedure.

Output di esempio:

{
  "id": "mysqlOrphanedRoutinesCheck",
  "title": "Check for orphaned routines in 5.7",
  "status": "OK",
  "description": "Error: The following routines have been orphaned. Schemas that they are referencing no longer exists.\nThey have to be cleaned up or the upgrade will fail.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "dropped_db.get_version",
        "description": "is orphaned"
      }
  ]
},

Il controllo preliminare segnala che la stored procedure get_version nel database dropped_db è orfana.

Per eseguire la pulizia di questa procedura, è possibile creare nuovamente lo schema mancante.

mysql> create database dropped_db;
Query OK, 1 row affected (0.01 sec)

Una volta creato nuovamente lo schema, è possibile interrompere la procedura per consentire il proseguimento dell’aggiornamento.

{
  "id": "mysqlOrphanedRoutinesCheck",
  "title": "Check for orphaned routines in 5.7",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

I nomi delle tabelle nello schema mysql sono in conflitto con le nuove tabelle in MySQL 8.0

Il nuovo Atomic Data Dictionary introdotto in MySQL 8.0 memorizza tutti i metadati in un set di tabelle InnoDB interne nello schema mysql. Durante l’aggiornamento, le nuove tabelle interne del dizionario dei dati vengono create nello schema mysql. Per evitare collisioni di denominazione, che comporterebbero errori di aggiornamento, il controllo preliminare esamina tutti i nomi delle tabelle dello schema mysql per assicurarsi che nessuno dei nuovi nomi di tabella sia già in uso. In caso affermativo, viene restituito un errore e l’aggiornamento non può continuare.

Output di esempio:

{
  "id": "mysqlSchema",
  "title": "Table names in the mysql schema conflicting with new tables in the latest MySQL.",
  "status": "OK",
  "description": "Error: The following tables in mysql schema have names that will conflict with the ones introduced in the latest version. They must be renamed or removed before upgrading (use RENAME TABLE command). This may also entail changes to applications that use the affected tables.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/upgrade-before-you-begin.html",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "mysql.tablespaces",
        "description": "Table name used in mysql schema.",
        "dbObjectType": "Table"
      }
  ]
}

Viene restituito un errore perché nello schema mysql è presente una tabella denominata tablespaces. Questo è uno dei nuovi nomi di tabella del dizionario dei dati interno di MySQL 8.0. È necessario rinominare o rimuovere tali tabelle prima dell’aggiornamento, utilizzando il comando RENAME TABLE.

Livello di controllo preliminare: errore

Tabelle partizionate utilizzando motori con partizionamento non nativo

Secondo la documentazione di MySQL 8.0, due motori di archiviazione attualmente forniscono supporto nativo per il partizionamento: InnoDB e NDB. Di questi, solo InnoDB è supportato in Aurora MySQL versione 3, che è compatibile con MySQL 8.0. Ogni tentativo di creare tabelle partizionate in MySQL 8.0 utilizzando qualsiasi altro motore di archiviazione fallisce. Questo controllo preliminare cerca le tabelle nel cluster di database che utilizzano il partizionamento non nativo. Se ne vengono restituite alcune, è necessario rimuovere il partizionamento o convertire il motore di archiviazione in InnoDB.

Output di esempio:

{
  "id": "nonNativePartitioning",
  "title": "Partitioned tables using engines with non native partitioning",
  "status": "OK",
  "description": "Error: In the latest MySQL storage engine is responsible for providing its own partitioning handler, and the MySQL server no longer provides generic partitioning support. InnoDB and NDB are the only storage engines that provide a native partitioning handler that is supported in the latest MySQL. A partitioned table using any other storage engine must be altered—either to convert it to InnoDB or NDB, or to remove its partitioning—before upgrading the server, else it cannot be used afterwards.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-configuration-changes",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.partMyisamTable",
         "description": "MyISAM engine does not support native partitioning",
         "dbObjectType": "Table"
      }
  ]
}

In questo esempio, una tabella MyISAM utilizza il partizionamento, che richiede un’azione prima che l’aggiornamento possa procedere.

Livello di controllo preliminare: errore

Utilizzo di un tipo di dato temporale obsoleto

I dati temporali obsoleti sono le colonne di tipo temporale (come TIMESTAMP e DATETIME) create nelle versioni di MySQL 5.5 e precedenti. In MySQL 8.0, il supporto per questi tipi di dati temporali obsoleti è stato rimosso, il che significa che gli aggiornamenti in loco da MySQL 5.7 a 8.0 non sono possibili se il database contiene questi tipi di dati temporali obsoleti. Per risolvere questo problema, è necessario creare nuovamente tutte le tabelle contenenti questi tipi di dati temporali obsoleti prima di procedere con l’aggiornamento.

Per ulteriori informazioni sulla definizione come obsoleti dei suddetti tipi di dati temporali in MySQL 5.7, consulta questo blog. Per ulteriori informazioni sulla rimozione dei tipi di dati temporali obsoleti in MySQL 8.0, consulta questo blog.

Output di esempio:

{
  "id": "oldTemporalCheck",
  "title": "Usage of old temporal type",
  "status": "OK",
  "description": "Error: Following table columns use a deprecated and no longer supported temporal disk storage format. They must be converted to the new format before upgrading. It can by done by rebuilding the table using 'ALTER TABLE <table_name> FORCE' command",
  "documentationLink": "https://dev.mysql.com/blog-archive/mysql-8-0-removing-support-for-old-temporal-datatypes/",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.55_temporal_table.timestamp_column",
        "description": "timestamp /* 5.5 binary format */",
        "dbObjectType": "Column"
      }
  ]
},

Viene segnalato un errore per la colonna timestamp_column della tabella test.55_temporal_table, poiché utilizza un formato di archiviazione su disco con dati temporali obsoleti che non è più supportato.

Per risolvere questo problema e consentire il proseguimento dell’aggiornamento, crea nuovamente la tabella per convertire il formato di archiviazione su disco temporale obsoleto in quello nuovo introdotto in MySQL 5.6. Per ulteriori informazioni e prerequisiti prima di procedere, consulta Converting between 3-byte and 4-byte Unicode character sets nella documentazione di MySQL.

L’esecuzione del comando seguente per ricostruire le tabelle menzionate in questo controllo preliminare converte i tipi di dati temporali obsoleti nel formato più recente con una precisione di frazioni di secondo.

ALTER TABLE ... ENGINE=InnoDB;

Per ulteriori informazioni su come creare nuovamente le tabelle, consulta ALTER TABLE statement nella documentazione di MySQL.

Dopo aver creato nuovamente la tabella in questione e riavviato l’aggiornamento, il controllo di compatibilità viene superato e l’aggiornamento può procedere.

{
  "id": "oldTemporalCheck",
  "title": "Usage of old temporal type",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Utilizzo di tabelle partizionate in tablespace condivisi

A partire da MySQL 8.0.13, il supporto per l’inserimento di partizioni di tabelle in tablespace condivisi è stato rimosso. Prima dell’aggiornamento, sposta tali tabelle dai tablespace condivisi ai tablespace file-per-table.

Output di esempio:

{
  "id": "partitionedTablesInSharedTablespaceCheck",
  "title": "Usage of partitioned tables in shared tablespaces",
  "status": "OK",
  "description": "Error: The following tables have partitions in shared tablespaces. They need to be moved to file-per-table tablespace before upgrading. You can do this by running query like 'ALTER TABLE table_name REORGANIZE PARTITION X INTO (PARTITION X VALUES LESS THAN (30) TABLESPACE=innodb_file_per_table);'",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/mysql-nutshell.html#mysql-nutshell-removals",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.partInnoDBTable",
        "description": "Partition p1 is in shared tablespace innodb",
        "dbObjectType": "Table"
      }
  ]
}

Il controllo preliminare non riesce perché la partizione p1 dalla tabella test.partInnoDBTable si trova nel tablespace di sistema.

Per risolvere questo problema, crea nuovamente la tabella test.partInnodbTable inserendo la partizione p1 che causa il problema in un tablespace file-per-table.

mysql > ALTER TABLE partInnodbTable REORGANIZE PARTITION p1
    ->   INTO (PARTITION p1 VALUES LESS THAN ('2014-01-01') TABLESPACE=innodb_file_per_table);
Query OK, 0 rows affected, 1 warning (0.02 sec)
Records: 0  Duplicates: 0  Warnings: 0

A questo punto, il controllo preliminare viene superato.

{
  "id": "partitionedTablesInSharedTablespaceCheck",
  "title": "Usage of partitioned tables in shared tablespaces",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Utilizzo di funzioni rimosse dalla versione più recente di MySQL

In MySQL 8.0, sono state rimosse alcune funzioni integrate. Questo controllo preliminare esamina il database alla ricerca di oggetti che potrebbero utilizzare queste funzioni. Se vengono trovati tali oggetti, viene restituito un errore. È necessario risolvere i problemi prima di tentare di eseguire nuovamente l’aggiornamento.

La maggior parte delle funzioni rimosse sono funzioni spaziali, che sono state sostituite con funzioni ST_* equivalenti. In questi casi, occorre modificare gli oggetti del database in modo da utilizzare la nuova denominazione delle procedure. Per ulteriori informazioni, consulta Features Removed in MySQL 8.0 nella documentazione MySQL.

Output di esempio:

{
  "id": "removedFunctionsCheck",
  "title": "Usage of removed functions",
  "status": "OK",
  "description": "Error: The following DB objects use functions that were removed in the latest MySQL version. Please make sure to update them to use supported alternatives before upgrade.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/mysql-nutshell.html#mysql-nutshell-removals",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.GetLocationsInPolygon",
        "description": "PROCEDURE uses removed function POLYGONFROMTEXT (consider using ST_POLYGONFROMTEXT instead)",
        "dbObjectType": "Routine"
      },
      {
        "level": "Error",
        "dbObject": "test.InsertLocation",
        "description": "PROCEDURE uses removed function POINTFROMTEXT (consider using ST_POINTFROMTEXT instead)",
        "dbObjectType": "Routine"
      }
  ]
},

Il controllo preliminare segnala che la stored procedure test.GetLocationsInPolygon utilizza due funzioni rimosse: POLYGONFROMTEXT e POINTFROMTEXT. Suggerisce inoltre di utilizzare le nuove funzioni ST_POLYGONFROMTEXT e ST_POINTFROMTEXT come sostitute. Dopo aver creato nuovamente la procedura utilizzando i suggerimenti, il controllo preliminare viene completato correttamente.

{
  "id": "removedFunctionsCheck",
  "title": "Usage of removed functions",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Controllo della sintassi MySQL per oggetti simili a routine

MySQL 8.0 ha introdotto delle parole chiave riservate che non erano riservate in precedenza. Il controllo preliminare dell’aggiornamento valuta l’uso di parole chiave riservate nei nomi degli oggetti del database, nonché nelle relative definizioni e nel relativo corpo. Se il controllo rileva l’uso di parole chiave riservate negli oggetti del database, ad esempio stored procedure, funzioni, eventi e trigger, l’aggiornamento non riesce e viene pubblicato un errore nel file upgrade-prechecks.log. Per risolvere il problema, è necessario aggiornare le definizioni degli oggetti e racchiudere tali riferimenti tra virgolette singole (’) prima dell’aggiornamento. Per ulteriori informazioni sull’escape delle parole riservate in MySQL, consulta String literals nella documentazione di MySQL.

In alternativa, è possibile modificare il nome specificandone uno diverso, il che potrebbe richiedere modifiche all’applicazione.

Output di esempio:

{
  "id": "routineSyntaxCheck",
  "title": "MySQL syntax check for routine-like objects",
  "status": "OK",
  "description": "The following objects did not pass a syntax check with the latest MySQL grammar. A common reason is that they reference names that conflict with new reserved keywords. You must update these routine definitions and `quote` any such references before upgrading.",
  "documentationLink": "https://dev.mysql.com/doc/refman/en/keywords.html",
  "detectedProblems": [
      {
         "level": "Error",
         "dbObject": "test.select_res_word",
         "description": "at line 2,18: unexpected token 'except'",
         "dbObjectType": "Routine"
      }
  ]
}

Per risolvere il problema, consulta la definizione della routine.

SHOW CREATE PROCEDURE test.select_res_word\G

*************************** 1. row ***************************
           Procedure: select_res_word
            sql_mode: ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
    Create Procedure: CREATE PROCEDURE 'select_res_word'()
BEGIN
    SELECT * FROM except;
END
character_set_client: utf8
collation_connection: utf8_general_ci
  Database Collation: latin1_swedish_ci
1 row in set (0.00 sec)

La procedura utilizza una tabella denominata except, che è una nuova parola chiave in MySQL 8.0. Crea nuovamente la procedura evitando il valore letterale della stringa.

> drop procedure if exists select_res_word;
Query OK, 0 rows affected (0.00 sec)

> DELIMITER $$
 > CREATE PROCEDURE select_res_word()
    -> BEGIN
    ->     SELECT * FROM 'except';
    -> END$$
Query OK, 0 rows affected (0.00 sec)

 > DELIMITER ;

A questo punto, il controllo preliminare viene superato.

{
  "id": "routineSyntaxCheck",
  "title": "MySQL syntax check for routine-like objects",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Incongruenze dello schema derivanti dalla rimozione o dal danneggiamento dei file

Come descritto in precedenza, MySQL 8.0 ha introdotto l’Atomic Data Dictionary, che archivia tutti i metadati in un set di tabelle InnoDB interne nello schema mysql. Questa nuova architettura offre un modo transazionale e conforme agli standard ACID per gestire i metadati del database, risolvendo il problema di “Atomic DDL” derivante dal precedente approccio basato su file. Prima di MySQL 8.0, era possibile che gli oggetti dello schema diventassero orfani se un’operazione DDL veniva interrotta inaspettatamente. La migrazione dei metadati basati su file nelle nuove tabelle Atomic Data Dictionary durante l’aggiornamento garantisce che tali oggetti dello schema orfani non siano presenti nell’istanza database. Se vengono rilevati oggetti orfani, l’aggiornamento non riesce.

Per contribuire al rilevamento di questi oggetti orfani prima di iniziare l’aggiornamento, viene eseguito il controllo preliminare schemaInconsistencyCheck per garantire che tutti gli oggetti di metadati del dizionario di dati siano sincronizzati. Se vengono rilevati oggetti di metadati orfani, l’aggiornamento non procede. Per procedere con l’aggiornamento, esegui la pulizia degli oggetti di metadati orfani.

Se riscontri errori con questo controllo preliminare, apri un caso con il Supporto AWS per richiedere che l’incoerenza dei metadati venga risolta. In alternativa, puoi tentare nuovamente l’aggiornamento eseguendo un dump logico, quindi effettuando il ripristino su un nuovo cluster di database Aurora MySQL versione 3.

Output di esempio:

{
  "id": "schemaInconsistencyCheck",
  "title": "Schema inconsistencies resulting from file removal or corruption",
  "status": "OK",
  "description": "Error: Following tables show signs that either table datadir directory or frm file was removed/corrupted. Please check server logs, examine datadir to detect the issue and fix it before upgrade",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.schemaInconsistencyCheck_failure",
        "description": "present in INFORMATION_SCHEMA's INNODB_SYS_TABLES table but missing from TABLES table"
      }
  ]
}

Il controllo preliminare segnala che la tabella test.schemaInconsistencyCheck_failure contiene metadati incoerenti. In questo caso, la tabella esiste nei metadati del motore di archiviazione InnoDB (information_schema.INNODB_SYS_TABLES), ma non nei metadati di MySQL (information_schema.TABLES).

Livello di controllo preliminare: errore

Verifica la presenza di artefatti relativi alla funzionalità di ripristino Aurora DDL

Nell’ambito dell’implementazione della funzionalità di ripristino DDL (Data Definition Language) in Aurora MySQL, i metadati delle istruzioni DDL inflight vengono mantenuti nelle tabelle ddl_log_md_table e ddl_log_table nello schema mysql. L’implementazione di Aurora della funzionalità di ripristino DDL non è supportata dalla versione 3 in poi, poiché la funzionalità fa parte della nuova implementazione Atomic Data Dictionary in MySQL 8.0. Se durante i controlli di compatibilità sono in esecuzione delle istruzioni DDL, questo controllo preliminare potrebbe avere esito negativo. Si consiglia di eseguire l’aggiornamento mentre non è in esecuzione alcuna istruzione DDL.

Se questo controllo preliminare ha esito negativo senza che siano in esecuzione una o più istruzioni DDL, apri un caso con il Supporto AWS per richiedere che l’incoerenza dei metadati venga risolta. In alternativa, puoi tentare nuovamente l’aggiornamento eseguendo un dump logico, quindi effettuando il ripristino su un nuovo cluster di database Aurora MySQL versione 3.

Se sono in esecuzione delle istruzioni DDL, l’output del controllo preliminare stampa il seguente messaggio:

“There are DDL statements in process. Please allow DDL statements to finish before upgrading.”

Output di esempio:

{
  "id": "auroraCheckDDLRecovery",
  "title": "Check for artifacts related to Aurora DDL recovery feature",
  "status": "OK",
  "description": "Aurora implementation of DDL recovery is not supported from 3.x onwards. This check verifies that the database do not have artifacts realted to the feature",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "mysql.ddl_log_md_table",
        "description": "Table mysql.ddl_log_md_table is not empty. Your database has pending DDL recovery operations. Reachout to AWS support for assistance."
      },
      {
        "level": "Error",
        "dbObject": "mysql.ddl_log_table",
        "description": "Table mysql.ddl_log_table is not empty. Your database has pending DDL recovery operations. Reachout to AWS support for assistance."
      },
      {
        "level": "Error",
        "dbObject": "information_schema.processlist",
        "description": "There are DDL statements in process. Please allow DDL statements to finish before upgrading."
      }
  ]
}

Il controllo preliminare ha restituito un errore dovuto a un DDL inflight eseguito contemporaneamente ai controlli di compatibilità. Si consiglia di tentare di eseguire nuovamente l’aggiornamento senza che siano in esecuzione le istruzioni DDL.

Livello di controllo preliminare: errore

Verifica l’esistenza della tabella mysql.rds_upgrade_prechecks

Si tratta di un controllo preliminare solo interno eseguito dal servizio RDS. Eventuali errori vengono gestiti automaticamente durante l’aggiornamento e possono essere ignorati senza problemi.

Se riscontri errori con questo controllo preliminare, apri un caso con il Supporto AWS per richiedere che l’incoerenza dei metadati venga risolta. In alternativa, puoi tentare nuovamente l’aggiornamento eseguendo un dump logico, quindi effettuando il ripristino su un nuovo cluster di database Aurora MySQL versione 3.

{
  "id": "auroraCheckRdsUpgradePrechecksTable",
  "title": "Check existence of mysql.rds_upgrade_prechecks table",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di artefatti relativi alla funzionalità Fast DDL di Aurora

L’ottimizzazione Fast DDL è stata introdotta in modalità Lab in Aurora MySQL versione 2 per migliorare l’efficienza di alcune operazioni DDL. In Aurora MySQL versione 3, la modalità Lab è stata rimossa e l’implementazione Fast DDL è stata sostituita dalla funzionalità MySQL 8.0 denominata Instant DDL.

Prima dell’aggiornamento ad Aurora MySQL versione 3, tutte le tabelle che utilizzano Fast DDL in modalità Lab dovranno essere create nuovamente eseguendo il comando OPTIMIZE TABLE o ALTER TABLE ... ENGINE=InnoDB per garantire la compatibilità con Aurora MySQL versione 3.

Questo controllo preliminare restituisce un elenco di tutte le tabelle di questo tipo. Dopo che le tabelle restituite sono state create nuovamente, è possibile tentare di eseguire nuovamente l’aggiornamento.

Output di esempio:

{
  "id": "auroraFODUpgradeCheck",
  "title": "Check for artifacts related to Aurora fast DDL feature",
  "status": "OK",
  "description": "Aurora fast DDL is not supported from 3.x onwards. This check verifies that the database does not have artifacts related to the feature",
  "documentationLink": "https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Managing.FastDDL.html#AuroraMySQL.Managing.FastDDL-v2",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.test",
        "description": "Your table has pending Aurora fast DDL operations. Run 'OPTIMIZE TABLE <table name>' for the table to apply all the pending DDL updates. Then try the upgrade again."
      }
  ]
}

Il controllo preliminare segnala che nella tabella test.test sono presenti operazioni Fast DDL in sospeso.

Per consentire il proseguimento dell’aggiornamento, è possibile creare nuovamente la tabella, quindi tentare di eseguire di nuovo l’aggiornamento.

mysql> optimize table test.test;
+-----------+----------+----------+-------------------------------------------------------------------+
| Table     | Op       | Msg_type | Msg_text                                                          |
+-----------+----------+----------+-------------------------------------------------------------------+
| test.test | optimize | note     | Table does not support optimize, doing recreate + analyze instead |
| test.test | optimize | status   | OK                                                                |
+-----------+----------+----------+-------------------------------------------------------------------+
2 rows in set (0.04 sec)

Dopo aver creato nuovamente la tabella, il controllo preliminare ha esito positivo.

{
  "id": "auroraFODUpgradeCheck",
  "title": "Check for artifacts related to Aurora fast DDL feature",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Tabelle con riferimento all’indice FULLTEXT dangling

Prima di MySQL 5.6.26, era possibile che, dopo aver eliminato un indice di ricerca full-text, le colonne nascoste FTS_DOC_ID e FTS_DOC_ID_INDEX diventassero orfane. Per ulteriori informazioni, consulta Bug #76012.

Se sono presenti tabelle create in versioni precedenti di MySQL per cui è stato riscontrato quanto descritto sopra, l’aggiornamento ad Aurora MySQL versione 3 può non riuscire. Questo controllo preliminare verifica che nel cluster di database non esistano tali indici full-text orfani o dangling prima dell’aggiornamento a MySQL 8.0. Se questo controllo preliminare ha esito negativo, crea nuovamente tutte le tabelle che contengono tali indici full-text dangling.

Output di esempio:

{
  "id": "auroraGetDanglingFulltextIndex",
  "title": "Tables with dangling FULLTEXT index reference",
  "status": "OK",
  "description": "Error: The following tables contain dangling FULLTEXT index which is not supported. It is recommended to rebuild the table before upgrade.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.table_with_fts_index",
        "description": "Table `test.table_with_fts_index` contains dangling FULLTEXT index. Kindly recreate the table before upgrade."
      }
  ]
},

Il controllo preliminare segnala un errore per la tabella test.table_with_fts_index perché contiene un indice full-text dangling. Per consentire il proseguimento dell’aggiornamento, crea nuovamente la tabella per eseguire la pulizia delle tabelle ausiliarie con indice full-text. Utilizza OPTIMIZE TABLE test.table_with_fts_index o ALTER TABLE test.table_with_fts_index, ENGINE=INNODB.

Dopo aver creato nuovamente la tabella, il controllo preliminare ha esito positivo.

{
  "id": "auroraGetDanglingFulltextIndex",
  "title": "Tables with dangling FULLTEXT index reference",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Verifica l’eventuale presenza di incoerenze relative al percorso di file ibd

Questo controllo preliminare si applica solo ad Aurora MySQL versione 3.03.0 e precedenti. Se si verifica un errore con questo controllo preliminare, esegui l’aggiornamento ad Aurora MySQL versione 3.04 o successive.

Output di esempio:

{
  "id": "auroraUpgradeCheckForDatafilePathInconsistency",
  "title": "Check for inconsistency related to ibd file path.",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di un indice full-text con ID di spazio pari a zero

In MySQL, quando si aggiunge un indice full-text a una tabella InnoDB, vengono creati alcuni tablespace di indici ausiliari. A causa di un bug nelle versioni precedenti di MySQL, poi corretto nella versione 5.6.20, era possibile che queste tabelle di indici ausiliari fossero state create nel tablespace di sistema, anziché nel tablespace InnoDB.

Se esistono tablespace ausiliari di questo tipo, l’aggiornamento non riesce. Crea nuovamente gli indici full-text indicati nell’errore del controllo preliminare, quindi tenta di eseguire di nuovo l’aggiornamento.

Output di esempio:

{
  "id": "auroraUpgradeCheckForFtsSpaceIdZero",
  "title": "Check for fulltext index with space id as zero",
  "status": "OK",
  "description": "The auxiliary tables of FTS indexes on the table are created in system table-space. Due to this DDL queries executed on MySQL8.0 shall cause database unavailability. To avoid that, drop and recreate all the FTS indexes on the table or rebuild the table using ALTER TABLE query before the upgrade.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.fts_space_zero_check",
        "description": " The auxiliary tables of FTS indexes on the table 'test.fts_space_zero_check' are created in system table-space due to https://bugs.mysql.com/bug.php?id=72132. In MySQL8.0, DDL queries executed on this table shall cause database unavailability. To avoid that, drop and recreate all the FTS indexes on the table or rebuild the table using ALTER TABLE query before the upgrade."
      }
  ]
},

Il controllo preliminare segnala un errore per la tabella test.fts_space_zero_check, poiché include tabelle ausiliarie di ricerca full-text (FTS) nel tablespace di sistema.

Dopo aver eliminato e creato nuovamente gli indici FTS associati a questa tabella, il controllo preliminare ha esito positivo.

{
 "id": "auroraUpgradeCheckForFtsSpaceIdZero",
 "title": "Check for fulltext index with space id as zero",
 "status": "OK",
 "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di transazioni XA in stato preparato

Durante l’esecuzione del processo di aggiornamento a una versione principale, è essenziale che l’istanza database Aurora MySQL versione 2 sia sottoposta a un arresto pulito. Ciò garantisce che tutte le transazioni vengano eseguite o ripristinate e che InnoDB abbia eliminato tutti i record del log di undo. Poiché il rollback delle transazioni è necessario, se il database contiene transazioni XA in stato preparato, può impedire il proseguimento dell’arresto pulito. Per questo motivo, se vengono rilevate transazioni XA preparate, l’aggiornamento non potrà procedere finché non si interverrà per eseguirne il commit o il rollback.

Per ulteriori informazioni sulla ricerca di transazioni XA in stato preparato utilizzando XA RECOVER, consulta XA transaction SQL statements nella documentazione di MySQL. Per ulteriori informazioni sugli stati delle transazioni XA, consulta XA transaction states nella documentazione di MySQL.

Output di esempio:

{
  "id": "auroraUpgradeCheckForIncompleteXATransactions",
  "title": "Pre-checks for XA Transactions in prepared state.",
  "status": "OK",
  "description": "Your cluster currently has XA transactions in the prepared state. To proceed with the upgrade, commit or rollback these transactions.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "all",
        "description": "Your cluster currently has XA transactions in the prepared state. To proceed with the upgrade, commit or rollback these transactions."
      }
  ]
}

Questo controllo preliminare segnala un errore perché vi sono transazioni in stato preparato di cui deve essere eseguito il commit o il rollback.

Dopo aver effettuato l’accesso al database, puoi controllare la tabella information_schema.innodb_trx e l’output XA RECOVER per ulteriori informazioni.

mysql> select trx_started,
    trx_mysql_thread_id,
    trx_id,trx_state,
    trx_operation_state,
    trx_rows_modified,
    trx_rows_locked 
from 
    information_schema.innodb_trx;
+---------------------+---------------------+---------+-----------+---------------------+-------------------+-----------------+
| trx_started         | trx_mysql_thread_id | trx_id  | trx_state | trx_operation_state | trx_rows_modified | trx_rows_locked |
+---------------------+---------------------+---------+-----------+---------------------+-------------------+-----------------+
| 2024-08-12 01:09:39 |                   0 | 2849470 | RUNNING   | NULL                |                 1 |               0 |
+---------------------+---------------------+---------+-----------+---------------------+-------------------+-----------------+
1 row in set (0.00 sec)

mysql> xa recover;
+----------+--------------+--------------+--------+
| formatID | gtrid_length | bqual_length | data   |
+----------+--------------+--------------+--------+
|        1 |            6 |            0 | xatest |
+----------+--------------+--------------+--------+
1 row in set (0.00 sec)

In questo esempio, viene eseguito il rollback della transazione preparata.

mysql> XA ROLLBACK 'xatest';
Query OK, 0 rows affected (0.00 sec)
v
mysql> xa recover;
Empty set (0.00 sec)

Dopo il rollback della transazione XA, il controllo preliminare ha esito positivo.

{
  "id": "auroraUpgradeCheckForIncompleteXATransactions",
  "title": "Pre-checks for XA Transactions in prepared state.",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica se l’aggiornamento è supportato nella classe di istanza corrente

L’esecuzione di un aggiornamento in loco da Aurora MySQL versione 2.12.0 o 2.12.1, in cui la classe di istanza database di scrittura è db.r6i.32xlarge, al momento non è supportata. In questo caso, il controllo preliminare restituisce un errore. Per consentire il proseguimento dell’aggiornamento, puoi modificare la classe dell’istanza database impostandola su db.r6i.24xlarge o una versione precedente. Altrimenti puoi eseguire l’aggiornamento ad Aurora MySQL versione 2.12.2 o successiva, in cui l’aggiornamento in loco ad Aurora MySQL versione 3 è supportato su db.r6i.32xlarge.

Output di esempio:

{
  "id": "auroraUpgradeCheckForInstanceLimit",
  "title": "Checks if upgrade is supported on the current instance class",
  "status": "OK",
  "description": "Upgrade from Aurora Version 2.12.0 and 2.12.1 may fail for 32.xl and above instance class.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "all",
        "description": "Upgrade is not supported on this instance size for Aurora MySql Version 2.12.1. Before upgrading to Aurora MySql 3, please consider either: 1. Changing the instance class to 24.xl or lower. -or- 2. Upgrading to patch version 2.12.2 or higher."
      }
  ]
},

Il controllo preliminare restituisce un errore perché l’istanza database di scrittura utilizza la classe di istanza db.r6i.32xlarge ed è in esecuzione su Aurora MySQL versione 2.12.1.

Livello di controllo preliminare: errore

Verifica la presenza di utenti interni 8.0

Questo controllo preliminare si applica solo ad Aurora MySQL versione 3.03.0 e precedenti. Se si verifica un errore con questo controllo preliminare, esegui l’aggiornamento ad Aurora MySQL versione 3.04 o successive.

Output di esempio:

{
  "id": "auroraUpgradeCheckForInternalUsers",
  "title": "Check for 8.0 internal users.",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di caratteri utf8mb3 non validi nella definizione della vista

Questo controllo preliminare identifica le viste che contengono commenti con codifica dei caratteri non validi utf8mb3. In MySQL 8.0, viene applicata una convalida più rigorosa alla codifica dei caratteri nei metadati, inclusi i commenti delle viste. Se la definizione di una vista contiene caratteri che non sono validi nel set di caratteri utf8mb3, l’aggiornamento non riesce.

Per risolvere questo problema, modifica la definizione della vista per rimuovere o sostituire eventuali caratteri non BMP prima di tentare l’aggiornamento.

Output di esempio:

{
"id": "auroraUpgradeCheckForInvalidUtf8mb3CharacterStringInViews",
"title": "Check for invalid utf8mb3 character string.",
"status": "OK",
"description": "Definition of following view(s) has/have invalid utf8mb3 character string.",
"detectedProblems": [
        {
            "level": "Error",
            "dbObject": "precheck.utf8mb3_invalid_char_view",
            "description": "Definition of view precheck.utf8mb3_invalid_char_view contains an invalid utf8mb3 character string. This is due to https://bugs.mysql.com/bug.php?id=110177. To fix the inconsistency, we recommend you to modify the view definition to not use non-BMP characters and try the upgrade again."
        }
    ]
},

Il controllo preliminare segnala che la definizione della vista utf8mb3_invalid_char_view contiene caratteri utf8mb3 non validi nella relativa definizione.

Per risolvere questo problema, identifica la vista che contiene i caratteri non supportati e aggiorna i commenti. Innanzitutto, esamina la struttura della vista e identifica i commenti.

MySQL> SHOW CREATE VIEW precheck.utf8mb3_invalid_char_view\G
*************************** 1. row ***************************
                View: utf8mb3_invalid_char_view
        Create View: CREATE ALGORITHM=UNDEFINED DEFINER=`admin`@`%` SQL SECURITY DEFINER VIEW `utf8mb3_invalid_char_view` AS select 'This row contains a dolphin 🐬' AS `message`
character_set_client: utf8
collation_connection: utf8_general_ci
1 row in set, 1 warning (0.00 sec)

Dopo aver identificato la vista che contiene l’errore, sostituisci la vista con l’istruzione CREATE OR REPLACE VIEW.

MySQL> CREATE OR REPLACE VIEW precheck.utf8mb3_invalid_char_view AS select 'This view definition to not use non-BMP characters' AS message;

Dopo aver aggiornato tutte le definizioni di viste che contengono caratteri non supportati, il controllo preliminare viene superato e l’aggiornamento può procedere.

{
"id": "auroraUpgradeCheckForInvalidUtf8mb3ColumnComments",
"title": "Check for invalid utf8mb3 column comments.",
"status": "OK",
"detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di commenti non validi nella colonna utf8mb3

Questo controllo preliminare identifica le tabelle che contengono commenti delle colonne con codifica dei caratteri non validi utf8mb3. In MySQL 8.0, viene applicata una convalida più rigorosa alla codifica dei caratteri nei metadati, inclusi i commenti delle colonne. Se un commento di colonna contiene caratteri che non sono validi nel set di caratteri utf8mb3, l’aggiornamento non riuscirà.

Per risolvere questo problema, è necessario modificare i commenti delle colonne per rimuovere o sostituire eventuali caratteri non BMP prima di tentare l’aggiornamento. È possibile utilizzare l’istruzione ALTER TABLE per aggiornare i commenti della colonna.

Output di esempio:

{
  "id": "auroraUpgradeCheckForInvalidUtf8mb3ColumnComments",
  "title": "Check for invalid utf8mb3 column comments.",
  "status": "OK",
  "description": "Following table(s) has/have invalid utf8mb3 comments on the column/columns.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.t2",
        "description": "Table test.t2 has invalid utf8mb3 comments in it's column/columns. This is due to non-BMP characters in the comment field. To fix the inconsistency, we recommend you to modify comment fields to not use non-BMP characters and try the upgrade again."
      }
  ]
}

Il controllo preliminare segnala che la tabella test.t2 contiene caratteri utf8mb3 non validi in uno o più commenti della colonna, in particolare a causa della presenza di caratteri non BMP.

Per risolvere il problema, è possibile identificare le colonne problematiche e aggiornare i relativi commenti. Innanzitutto, esamina la struttura della tabella per identificare le colonne con commenti:

mysql> SHOW CREATE TABLE test.t2\G

Dopo aver identificato le colonne con commenti problematici, aggiornale utilizzando l’istruzione ALTER TABLE. Per esempio:

mysql> ALTER TABLE test.t2 MODIFY COLUMN column_name data_type COMMENT 'Updated comment without non-BMP characters';

In alternativa, è possibile rimuovere completamente il commento:

mysql> ALTER TABLE test.t2 MODIFY COLUMN column_name data_type COMMENT '';

Dopo aver aggiornato tutti i commenti delle colonne problematiche, il controllo preliminare verrà superato e l’aggiornamento potrà procedere:

{
  "id": "auroraUpgradeCheckForInvalidUtf8mb3ColumnComments",
  "title": "Check for invalid utf8mb3 column comments.",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di commenti non validi nell’indice utf8mb3

Questo controllo preliminare identifica le tabelle che contengono commenti degli indici con codifica dei caratteri non validi utf8mb3. In MySQL 8.0, viene applicata una convalida più rigorosa alla codifica dei caratteri nei metadati, inclusi i commenti degli indici. Se i commenti degli indici contengono caratteri che non sono validi nel set di caratteri utf8mb3, l’aggiornamento non riesce.

Per risolvere questo problema, è necessario modificare i commenti degli indici per rimuovere o sostituire eventuali caratteri non BMP prima di tentare l’aggiornamento.

Output di esempio:

{
    "id": "auroraUpgradeCheckForInvalidUtf8mb3IndexComments",
    "title": "Check for invalid utf8mb3 index comments.",
    "status": "OK",
    "description": "Following table(s) has/have invalid utf8mb3 comments on the index.",
    "detectedProblems": [
        {
            "level": "Error",
            "dbObject": "precheck.utf8mb3_tab_index_comment",
            "description": "Table precheck.utf8mb3_tab_index_comment has invalid utf8mb3 comments in it's index. This is due to https://bugs.mysql.com/bug.php?id=110177. To fix the inconsistency, we recommend you to modify comment fields to not use non-BMP characters and try the upgrade again."
        }
    ]
},

Il controllo preliminare segnala che la tabella utf8mb3_tab_index_comment contiene caratteri utf8mb3 non validi in uno o più commenti della colonna, in particolare a causa della presenza di caratteri non BMP.

Per risolvere questo problema, esamina innanzitutto la struttura della tabella per identificare l’indice con commenti problematici.

MySQL> SHOW CREATE TABLE precheck.utf8mb3_tab_index_comment\G
*************************** 1. row ***************************
    Table: utf8mb3_tab_index_comment
Create Table: CREATE TABLE `utf8mb3_tab_index_comment` (
`id` int(11) DEFAULT NULL,
`name` varchar(100) DEFAULT NULL,
KEY `idx_name` (`name`) COMMENT 'Name index 🐬'
) ENGINE=InnoDB DEFAULT CHARSET=utf8
1 row in set (0.01 sec)

Una volta identificato l’indice che contiene commenti che utilizzano caratteri non supportati, eliminalo e crealo di nuovo.

MySQL> ALTER TABLE precheck.utf8mb3_tab_index_comment DROP INDEX idx_name;
MySQL> ALTER TABLE precheck.utf8mb3_tab_index_comment ADD INDEX idx_name(name);

L’esempio seguente mostra un altro modo per creare nuovamente l’indice.

MySQL> ALTER TABLE utf8mb3_tab_index_comment DROP INDEX idx_name, ADD INDEX idx_name (name) COMMENT 'Updated comment without non-BMP characters';

Dopo aver rimosso o aggiornato tutti i commenti degli indici non supportati, il controllo preliminare viene superato e l’aggiornamento può procedere.

{
"id": "auroraUpgradeCheckForInvalidUtf8mb3IndexComments",
"title": "Check for invalid utf8mb3 index comments.",
"status": "OK",
"detectedProblems": []
},

Livello di controllo preliminare: errore

Verifica la presenza di caratteri utf8mb3 non validi nella definizione della tabella

Questo controllo preliminare identifica le tabelle che contengono commenti con codifica dei caratteri non validi utf8mb3. In MySQL 8.0, viene applicata una convalida più rigorosa alla codifica dei caratteri nei metadati, inclusi i commenti delle tabelle. Se i commenti delle tabelle contengono caratteri che non sono validi nel set di caratteri utf8mb3, l’aggiornamento non riesce.

Per risolvere questo problema, è necessario modificare i commenti delle tabelle per rimuovere o sostituire eventuali caratteri non BMP prima di tentare l’aggiornamento.

Output di esempio:

{
    "id": "auroraUpgradeCheckForInvalidUtf8mb3TableComments",
    "title": "Check for invalid utf8mb3 table comments.",
    "status": "OK",
    "description": "Following table(s) has/have invalid utf8mb3 comments.",
    "detectedProblems": [
        {
            "level": "Error",
            "dbObject": "precheck.utf8mb3_table_with_comment",
            "description": "Table precheck.utf8mb3_table_with_comment has invalid utf8mb3 comments. This is due to https://bugs.mysql.com/bug.php?id=110177. To fix the inconsistency, we recommend you to modify comment fields to not use non-BMP characters and try the upgrade again."
        }
        
    ]
},

Il controllo preliminare segnala i commenti utf8mb3 non validi definiti per le tabelle utf8mb3_table_with_comment nel database di test.

Per risolvere questo problema, identifica la tabella che contiene i caratteri non supportati e aggiorna i commenti. Innanzitutto, esamina la struttura della tabella vista e identifica i commenti.

MySQL> SHOW CREATE TABLE precheck.utf8mb3_table_with_comment\G
*************************** 1. row ***************************
    Table: utf8mb3_table_with_comment
Create Table: CREATE TABLE `utf8mb3_table_with_comment` (
`id` int(11) NOT NULL,
`name` varchar(100) DEFAULT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='This table comment contains flag 🏳️'
1 row in set (0.00 sec)

Dopo aver identificato i commenti delle tabelle che contengono caratteri non supportati, aggiorna i commenti con l’istruzione ALTER TABLE.

MySQL> ALTER TABLE precheck.utf8mb3_table_with_comment COMMENT='Updated comment without non-BMP characters';

In alternativa, è possibile rimuovere il commento.

MySQL> ALTER TABLE precheck.utf8mb3_table_with_comment COMMENT='';

Dopo aver rimosso tutti i caratteri non supportati da tutti i commenti delle tabelle, il controllo preliminare ha esito positivo.

{
"id": "auroraUpgradeCheckForInvalidUtf8mb3TableComments",
"title": "Check for invalid utf8mb3 table comments.",
"status": "OK",
"detectedProblems": []
},

Livello di controllo preliminare: errore

Verifica se esiste un utente master RDS

MySQL 8 ha aggiunto un nuovo modello di privilegi con supporto per il ruolo e i privilegi dinamici per rendere la gestione dei privilegi più semplice e dettagliata. Come parte di questa modifica, Aurora MySQL ha introdotto il nuovo rds_superuser_role, che viene automaticamente concesso all’utente master del database al momento dell’aggiornamento da Aurora MySQL versione 2 alla versione 3.

Per ulteriori informazioni sui ruoli e i privilegi assegnati all’utente master in Aurora MySQL, consulta Privilegi dell'account utente master. Per ulteriori informazioni sul modello di privilegi basato su ruolo in Aurora MySQL versione 3, consulta Privilegio basato sui ruoli.

Questo controllo preliminare verifica che l’utente master esista nel database. Se l’utente master non esiste, il controllo preliminare avrà esito negativo. Per consentire il proseguimento dell’aggiornamento, crea nuovamente l’utente master reimpostando la password dell’utente principale o creando manualmente l’utente. Prova quindi a eseguire nuovamente l’aggiornamento. Per ulteriori informazioni sulla reimpostazione della password dell’utente master, consulta Modifica della password per l’utente master del database.

Output di esempio:

{
  "id": "auroraUpgradeCheckForMasterUser",
  "title": "Check if master user exists",
  "status": "OK",
  "description": "Throws error if master user has been dropped!",
  "documentationLink": "https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.MasterAccounts.html",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "all",
        "description": "Your Master User on host '%' has been dropped. To proceed with the upgrade, recreate the master user `reinvent` on default host '%'"
      }
  ]
}

Dopo aver reimpostato la password dell’utente master, il controllo preliminare verrà superato e potrai tentare di eseguire nuovamente l’aggiornamento.

L’esempio seguente utilizza l’interfaccia AWS CLI per reimpostare la password. Le modifiche alla password vengono applicate immediatamente.

aws rds modify-db-cluster \
    --db-cluster-identifier my-db-cluster \
    --master-user-password my-new-password

Quindi il controllo preliminare ha esito positivo.

{
  "id": "auroraUpgradeCheckForMasterUser",
  title": "Check if master user exists",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di colonne di geometria negli indici dei prefissi

A partire da MySQL 8.0.12, non è più possibile creare un indice con prefisso in una colonna utilizzando il tipo di dati GEOMETRY. Per ulteriori informazioni, consulta WL#11808.

Se esistono indici di questo tipo, l’aggiornamento non riesce. Per risolvere il problema, elimina gli indici GEOMETRY con prefisso nelle tabelle menzionate nell’errore del controllo preliminare.

Output di esempio:

{
  "id": "auroraUpgradeCheckForPrefixIndexOnGeometryColumns",
  "title": "Check for geometry columns on prefix indexs",
  "status": "OK",
  "description": "Consider dropping the prefix Indexes of geometry columns and restart the upgrade.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.geom_index_prefix",
        "description": "Table `test`.`geom_index_prefix` has an index `LatLon` on geometry column/s. Mysql 8.0 does not support this type of index on a geometry column https://dev.mysql.com/worklog/task/?id=11808. To upgrade to MySQL 8.0, Run 'DROP INDEX `LatLon` ON `test`.`geom_index_prefix`;"
      }
  ]
}

Il controllo preliminare segnala un errore perché la tabella test.geom_index_prefix contiene un indice con un prefisso in una colonna GEOMETRY.

Dopo aver eliminato questo indice, il controllo preliminare ha esito positivo.

{
  "id": "auroraUpgradeCheckForPrefixIndexOnGeometryColumns",
  "title": "Check for geometry columns on prefix indexs",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica l’eventuale presenza di incoerenze relative ai caratteri speciali nelle stored procedure

Prima di MySQL 8.0, i nomi dei database, i nomi delle tabelle e altri oggetti corrispondevano ai file nella directory dei dati, ossia a metadati basati su file. Nell’ambito dell’aggiornamento a MySQL 8.0, viene eseguita la migrazione di tutti gli oggetti del database nelle nuove tabelle interne del dizionario dei dati, che sono archiviate nello schema mysql per supportare l’Atomic Data Dictionary appena implementato. Nell’ambito della migrazione delle stored procedure, la definizione e il corpo di ciascuna procedura vengono convalidati man mano che vengono acquisiti nel nuovo dizionario di dati.

Prima di MySQL 8, in alcuni casi era possibile creare routine memorizzate o inserire direttamente nella tabella mysql.proc procedure che contenevano caratteri speciali. Ad esempio, era possibile creare una stored procedure contenente un commento con il carattere spazio non divisibile non conforme \xa0. Se viene rilevata una di queste procedure, l’aggiornamento non riesce.

Questo controllo preliminare verifica che i corpi e le definizioni delle stored procedure non contengano tali caratteri. Per consentire il proseguimento dell’aggiornamento, crea nuovamente queste stored procedure senza caratteri nascosti o speciali.

Output di esempio:

{
  "id": "auroraUpgradeCheckForSpecialCharactersInProcedures",
  "title": "Check for inconsistency related to special characters in stored procedures.",
  "status": "OK",
  "description": "Following procedure(s) has special characters inconsistency.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "information_schema.routines",
        "description": "Data Dictionary Metadata is inconsistent for the procedure `get_version_proc` in the database `test` due to usage of special characters in procedure body. To avoid that, drop and recreate the procedure without any special characters before proceeding with the Upgrade."
      }
  ]
}

Il controllo preliminare segnala che il cluster di database contiene una procedura denominata get_version_proc nel database test che contiene caratteri speciali nel corpo della procedura.

Dopo aver eliminato e creato nuovamente la stored procedure, il controllo preliminare ha esito positivo e consente di procedere con l’aggiornamento.

{
  "id": "auroraUpgradeCheckForSpecialCharactersInProcedures",
  "title": "Check for inconsistency related to special characters in stored procedures.",
  "status": "OK",
  "detectedProblems": []
},

Livello di controllo preliminare: errore

Verifica l’eventuale mancata corrispondenza del tipo di oggetto per lo schema sys

Lo schema sys è un set di oggetti e viste in un database MySQL che aiuta gli utenti a eseguire la risoluzione dei problemi, l’ottimizzazione e il monitoraggio per le relative istanze database. Quando si esegue un aggiornamento di versione principale da Aurora MySQL versione 2 alla versione 3, le viste dello schema sys vengono create nuovamente e aggiornate alle nuove definizioni di Aurora MySQL versione 3.

Nell’ambito dell’aggiornamento, se alcuni oggetti dello schema sys vengono definiti utilizzando i motori di archiviazione (sys_config/BASE TABLE in INFORMATION_SCHEMA.TABLES) anziché le viste, l’aggiornamento non riesce. Tali tabelle si trovano nella tabella information_schema.tables. Questo non è un comportamento previsto, ma in alcuni casi può verificarsi a causa di un errore dell’utente.

Questo controllo preliminare convalida tutti gli oggetti dello schema sys per garantire che utilizzino le definizioni di tabella corrette e che le viste non vengano erroneamente definite come tabelle InnoDB o MyISAM. Per risolvere il problema, correggi manualmente gli oggetti restituiti rinominandoli o eliminandoli. Prova quindi a eseguire nuovamente l’aggiornamento.

Output di esempio:

{
  "id": "auroraUpgradeCheckForSysSchemaObjectTypeMismatch",
  "title": "Check object type mismatch for sys schema.",
  "status": "OK",
  "description": "Database contains objects with type mismatch for sys schema.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "sys.waits_global_by_latency",
        "description": "Your object sys.waits_global_by_latency has a type mismatch. To fix the inconsistency we recommend to rename or remove the object before upgrading (use RENAME TABLE command). "
      }
  ]
}

Il controllo preliminare segnala che la vista sys.waits_global_by_latency nello schema sys presenta una mancata corrispondenza del tipo che impedisce il proseguimento dell’aggiornamento.

Dopo aver effettuato l’accesso all’istanza database, puoi vedere che questo oggetto è definito come una tabella InnoDB, mentre invece dovrebbe essere una vista.

mysql> show create table sys.waits_global_by_latency\G
*************************** 1. row ***************************
       Table: waits_global_by_latency
Create Table: CREATE TABLE `waits_global_by_latency` (
  `events` varchar(128) DEFAULT NULL,
  `total` bigint(20) unsigned DEFAULT NULL,
  `total_latency` text,
  `avg_latency` text,
  `max_latency` text
) ENGINE=InnoDB DEFAULT CHARSET=utf8
1 row in set (0.00 sec)

Per risolvere questo problema, è possibile eliminare e creare nuovamente la vista con la definizione corretta o rinominarla. Durante il processo di aggiornamento, la vista viene creata automaticamente con la definizione di tabella corretta.

mysql> RENAME TABLE sys.waits_global_by_latency to sys.waits_global_by_latency_old;
Query OK, 0 rows affected (0.01 sec)

A questo punto, il controllo preliminare viene superato.

{
  "id": "auroraUpgradeCheckForSysSchemaObjectTypeMismatch",
  "title": "Check object type mismatch for sys schema.",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Controlla il limite massimo per il nome della colonna nella vista

La lunghezza massima consentita per un nome di colonna in MySQL è di 64 caratteri. Prima di MySQL 8.0, in alcuni casi era possibile creare una vista con un nome di colonna più lungo di 64 caratteri. Se nell’istanza database sono presenti viste di questo tipo, viene restituito un errore di controllo preliminare e l’aggiornamento non riesce. Per consentire il proseguimento dell’aggiornamento, è necessario creare nuovamente le viste in questione, assicurandosi che la lunghezza delle colonne sia inferiore a 64 caratteri. Prova quindi a eseguire nuovamente l’aggiornamento.

Output di esempio:

{
  "id": "auroraUpgradeCheckForViewColumnNameLength",
  "title": "Check for upperbound limit related to column name in view.",
  "status": "OK",
  "description": "Following view(s) has column(s) with length greater than 64.",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.colname_view_test.col2_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad",
        "description": "View `test`.`colname_view_test`has column `col2_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad` with invalid column name length. To avoid Upgrade errors, view should be altered by renaming the column name so that its length is not 0 and doesn't exceed 64."
      }
  ]
}

Il controllo preliminare segnala che la vista test.colname_view_test contiene una colonna col2_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad che supera la lunghezza massima consentita di 64 caratteri.

Osservando la definizione della vista, possiamo individuare la colonna che causa l’errore.

mysql> desc `test`.`colname_view_test`;
+------------------------------------------------------------------+-------------+------+-----+---------+-------+
| Field                                                            | Type        | Null | Key | Default | Extra |
+------------------------------------------------------------------+-------------+------+-----+---------+-------+
| col1                                                             | varchar(20) | YES  |     | NULL    |       |
| col2_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad_pad | int(11)     | YES  |     | NULL    |       |
+------------------------------------------------------------------+-------------+------+-----+---------+-------+
2 rows in set (0.00 sec)

Per consentire il proseguimento dell’aggiornamento, crea nuovamente la vista, assicurandoti che la lunghezza delle colonne non superi i 64 caratteri.

mysql> drop view `test`.`colname_view_test`;
Query OK, 0 rows affected (0.01 sec)

mysql> create view `test`.`colname_view_test`(col1, col2_nopad) as select inf, fodcol from test;
Query OK, 0 rows affected (0.01 sec)

mysql> desc `test`.`colname_view_test`;
+------------+-------------+------+-----+---------+-------+
| Field      | Type        | Null | Key | Default | Extra |
+------------+-------------+------+-----+---------+-------+
| col1       | varchar(20) | YES  |     | NULL    |       |
| col2_nopad | int(11)     | YES  |     | NULL    |       |
+------------+-------------+------+-----+---------+-------+
2 rows in set (0.00 sec)

A questo punto, il controllo preliminare viene superato.

{
  "id": "auroraUpgradeCheckForViewColumnNameLength",
  "title": "Check for upperbound limit related to column name in view.",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica la presenza di tabelle con indici definiti con una lunghezza del prefisso superiore a 255 byte in colonne di dimensioni piccolissime

Quando si crea un indice su una colonna utilizzando un tipo di dati binario in MySQL, è necessario aggiungere una lunghezza del prefisso nella definizione dell’indice. Prima di MySQL 8.0, in alcuni casi era possibile specificare una lunghezza del prefisso superiore alle dimensioni massime consentite per tali tipi di dati. Un esempio è rappresentato dalle colonne TINYTEXT e TINYBLOB, in cui le dimensioni massime consentite dei dati sono di 255 byte, ma sono consentiti prefissi di indice di dimensioni superiori. Per ulteriori informazioni, consulta InnoDB limits nella documentazione di MySQL.

Se questo controllo preliminare ha esito negativo, elimina l’indice che causa l’errore o riduci la lunghezza del prefisso delle colonne TINYTEXT e TINYBLOB dell’indice a meno di 255 byte. Prova quindi a eseguire nuovamente l’aggiornamento.

Output di esempio:

{
  "id": "auroraUpgradeCheckIndexLengthLimitOnTinyColumns",
  "title": "Check for the tables with indexes defined with prefix length greater than 255 bytes on tiny columns",
  "status": "OK",
  "description": "Prefix length of the indexes defined on tiny columns cannot exceed 255 bytes. With utf8mb4 char set, this limits the prefix length supported upto 63 characters only. A larger prefix length was allowed in MySQL5.7 using innodb_large_prefix parameter. This parameter is deprecated in MySQL 8.0.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/innodb-limits.html, https://dev.mysql.com/doc/refman/8.0/en/storage-requirements.html",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.tintxt_prefixed_index.col1",
        "description": "Index 'PRIMARY' on tinytext/tinyblob column `col1` of table `test.tintxt_prefixed_index` is defined with prefix length exceeding 255 bytes. Reduce the prefix length to <=255 bytes depending on character set used. For utf8mb4, it should be <=63."
      }
  ]
}

Il controllo preliminare segnala un errore per la tabella test.tintxt_prefixed_index, poiché ha un indice PRIMARY con un prefisso di dimensioni superiori a 255 byte in una colonna TINYTEXT o TINYBLOB.

Osservando la definizione di questa tabella, possiamo vedere che la chiave primaria ha un prefisso 65 sulla colonna TINYTEXT col1. Poiché la tabella è definita utilizzando il set di caratteri utf8mb4, che memorizza 4 byte per carattere, il prefisso supera il limite di 255 byte.

mysql> show create table `test`.`tintxt_prefixed_index`\G
*************************** 1. row ***************************
       Table: tintxt_prefixed_index
Create Table: CREATE TABLE `tintxt_prefixed_index` (
  `col1` tinytext NOT NULL,
  `col2` tinytext,
  `col_id` tinytext,
  PRIMARY KEY (`col1`(65))
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC
1 row in set (0.00 sec)

Modificando il prefisso dell’indice su 63 durante l’utilizzo del set di caratteri utf8mb4, l’aggiornamento potrà proseguire.

mysql> alter table `test`.`tintxt_prefixed_index` drop PRIMARY KEY, ADD  PRIMARY KEY (`col1`(63));
Query OK, 0 rows affected (0.04 sec)
Records: 0  Duplicates: 0  Warnings: 0

A questo punto, il controllo preliminare viene superato.

{
  "id": "auroraUpgradeCheckIndexLengthLimitOnTinyColumns",
  "title": "Check for the tables with indexes defined with prefix length greater than 255 bytes on tiny columns",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: errore

Verifica eventuali incoerenze nei metadati InnoDB mancanti per la tabella mysql.host

Si tratta di un controllo preliminare solo interno eseguito dal servizio RDS. Eventuali errori vengono gestiti automaticamente durante l’aggiornamento e possono essere ignorati senza problemi.

Se riscontri errori con questo controllo preliminare, apri un caso con il Supporto AWS per richiedere che l’incoerenza dei metadati venga risolta. In alternativa, puoi tentare nuovamente l’aggiornamento eseguendo un dump logico, quindi effettuando il ripristino su un nuovo cluster di database Aurora MySQL versione 3.

Livello di controllo preliminare: avviso

Nuove considerazioni sul plugin di autenticazione predefinito

In MySQL 8.0, è stato introdotto il plugin di autenticazione caching_sha2_password, che offre una crittografia delle password più sicura e prestazioni migliori rispetto al plugin mysql_native_password obsoleto. Per Aurora MySQL versione 3, il plugin di autenticazione predefinito utilizzato per gli utenti del database è il plugin mysql_native_password.

Questo controllo preliminare avverte che tale plugin verrà rimosso e l’impostazione predefinita verrà modificata in una futura versione principale. Prendi in considerazione la possibilità di valutare la compatibilità dei client e degli utenti delle applicazioni prima di questa modifica.

Per ulteriori informazioni, consulta caching_sha2_password compatibility issues and solutions nella documentazione di MySQL.

Output di esempio:

{
  "id": "defaultAuthenticationPlugin",
  "title": "New default authentication plugin considerations",
  "description": "Warning: The new default authentication plugin 'caching_sha2_password' offers more secure password hashing than previously used 'mysql_native_password' (and consequent improved client connection authentication). However, it also has compatibility implications that may affect existing MySQL installations. If your MySQL installation must serve pre-8.0 clients and you encounter compatibility issues after upgrading, the simplest way to address those issues is to reconfigure the server to revert to the previous default authentication plugin (mysql_native_password). For example, use these lines in the server option file:\n\n[mysqld]\ndefault_authentication_plugin=mysql_native_password\n\nHowever, the setting should be viewed as temporary, not as a long term or permanent solution, because it causes new accounts created with the setting in effect to forego the improved authentication security.\nIf you are using replication please take time to understand how the authentication plugin changes may impact you.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-compatibility-issues\nhttps://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-replication"
},

Livello di controllo preliminare: avviso

Utilizzo di un flag sql_mode MAXDB obsoleto

In MySQL 8.0, sono state rimosse alcune opzioni di variabili di sistema sql_mode obsolete, una delle quali era MAXDB. Questo controllo preliminare esamina tutte le sessioni attualmente connesse, insieme alle routine e ai trigger, per garantire che sql_mode non sia impostato su una combinazione contenente MAXDB in alcun caso.

Output di esempio:

{
  "id": "maxdbFlagCheck",
  "title": "Usage of obsolete MAXDB sql_mode flag",
  "status": "OK",
  "description": "Warning: The following DB objects have the obsolete MAXDB option persisted for sql_mode, which will be cleared during the upgrade. It can potentially change the datatype DATETIME into TIMESTAMP if it is used inside object's definition, and this in turn can change the behavior in case of dates earlier than 1970 or later than 2037. If this is a concern, please redefine these objects so that they do not rely on the MAXDB flag before running the upgrade.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/mysql-nutshell.html#mysql-nutshell-removals",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "test.maxdb_stored_routine",
        "description": "PROCEDURE uses obsolete MAXDB sql_mode",
        "dbObjectType": "Routine"
      }
  ]
}

Il controllo preliminare segnala che la routine test.maxdb_stored_routine contiene un’opzione sql_mode non supportata.

Dopo aver effettuato l’accesso al database, è possibile visualizzare la definizione di routine in cui sql_mode contiene MAXDB.

 > SHOW CREATE PROCEDURE test.maxdb_stored_routine\G

*************************** 1. row ***************************
           Procedure: maxdb_stored_routine
            sql_mode: PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,MAXDB,NO_KEY_OPTIONS,NO_TABLE_OPTIONS,NO_FIELD_OPTIONS,NO_AUTO_CREATE_USER
    Create Procedure: CREATE DEFINER="msandbox"@"localhost" PROCEDURE "maxdb_stored_routine"()
BEGIN
    SELECT * FROM test;
END
character_set_client: utf8
collation_connection: utf8_general_ci
  Database Collation: latin1_swedish_ci
1 row in set (0.00 sec)

Per risolvere il problema, crea nuovamente la procedura dopo aver impostato l’opzione sql_mode corretta sul client.

Crea nuovamente la procedura senza l’opzione sql_mode non supportata.

mysql > set sql_mode='PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE';
Query OK, 0 rows affected, 1 warning (0.00 sec)

mysql > DROP PROCEDURE test.maxdb_stored_routine\G
Query OK, 0 rows affected (0.00 sec)

mysql >
mysql > DELIMITER $$
mysql >
mysql > CREATE PROCEDURE test.maxdb_stored_routine()
    -> SQL SECURITY DEFINER
    -> BEGIN
    ->     SELECT * FROM test;
    -> END$$
Query OK, 0 rows affected (0.00 sec)

mysql >
mysql > DELIMITER ;
mysql > show create procedure test.maxdb_stored_routine\G
*************************** 1. row ***************************
           Procedure: maxdb_stored_routine
            sql_mode: PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE
    Create Procedure: CREATE DEFINER="msandbox"@"localhost" PROCEDURE "maxdb_stored_routine"()
BEGIN
    SELECT * FROM test;
END
character_set_client: utf8
collation_connection: utf8_general_ci
  Database Collation: latin1_swedish_ci
1 row in set (0.00 sec)

Il controllo preliminare ha esito positivo.

{
  "id": "maxdbFlagCheck",
  "title": "Usage of obsolete MAXDB sql_mode flag",
  "status": "OK",
  "detectedProblems": []
}

Livello di controllo preliminare: avviso

Verifica l’utilizzo obsoleto dei simboli del dollaro singoli nei nomi degli oggetti

A partire da MySQL 8.0.32, l’utilizzo del simbolo del dollaro ($) come primo carattere di un identificatore senza virgolette è obsoleto. Se sono presenti schemi, tabelle, viste, colonne o routine contenenti un $ come primo carattere, il controllo preliminare restituisce un avviso. Sebbene questo avviso non impedisca il proseguimento dell’aggiornamento, è consigliabile agire subito per risolvere il problema. A partire da MySQL 8.4 qualsiasi identificatore di questo tipo restituisce un errore di sintassi anziché un avviso.

Output di esempio:

{
  "id": "mysqlDollarSignNameCheck",
  "title": "Check for deprecated usage of single dollar signs in object names",
  "status": "OK",
  "description": "Warning: The following objects have names with deprecated usage of dollar sign ($) at the begining of the identifier. To correct this warning, ensure, that names starting with dollar sign, also end with it, similary to quotes ($example$). ",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "test.$deprecated_syntx",
        "description": " name starts with $ sign."
      }
  ]
},

Il controllo preliminare segnala un avviso perché la tabella $deprecated_syntx nello schema test contiene un $ come primo carattere.

Livello di controllo preliminare: avviso

Utilizzo di oggetti di database con nomi in conflitto con nuove parole chiave riservate

Questo controllo è simile a routineSyntaxCheck, in quanto verifica l’utilizzo di oggetti di database con nomi in conflitto con nuove parole chiave riservate. Sebbene i due controlli non impediscano gli aggiornamenti, è necessario valutare attentamente gli avvisi.

Output di esempio:

Utilizzando l’esempio precedente con la tabella denominata except, il controllo preliminare restituisce un avviso:

{
  "id": "reservedKeywordsCheck",
  "title": "Usage of db objects with names conflicting with new reserved keywords",
  "status": "OK",
  "description": "Warning: The following objects have names that conflict with new reserved keywords. Ensure queries sent by your applications use `quotes` when referring to them or they will result in errors.",
  "documentationLink": "https://dev.mysql.com/doc/refman/en/keywords.html",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "test.except",
        "description": "Table name",
        "dbObjectType": "Table"
      }
  ]
}

Questo avviso segnala che potrebbero esserci alcune query dell’applicazione da esaminare. Se le query dell’applicazione non eseguono correttamente l’escape dei valori letterali delle stringhe, potrebbero verificarsi degli errori dopo l’aggiornamento a MySQL 8.0. Esamina le tue applicazioni per verificare, eseguendo test rispetto a un clone o uno snapshot del cluster di database Aurora MySQL in esecuzione sulla versione 3.

Esempio di una query dell’applicazione senza escape che avrà esito negativo dopo l’aggiornamento:

SELECT * FROM escape;

Esempio di una query dell’applicazione con escape corretto che avrà esito positivo dopo l’aggiornamento:

SELECT * FROM 'escape';

Livello di controllo preliminare: avviso

Utilizzo del set di caratteri utf8mb3

In MySQL 8.0, il set di caratteri utf8mb3 è obsoleto e verrà rimosso in una futura versione principale di MySQL. Questo controllo preliminare è implementato per generare un avviso se vengono rilevati oggetti di database che utilizzano tale set di caratteri. Anche se ciò non impedisce il proseguimento dell’aggiornamento, si consiglia vivamente di valutare la possibilità di eseguire la migrazione delle tabelle al set di caratteri utf8mb4, che è l’impostazione predefinita a partire da MySQL 8.0. Per ulteriori informazioni su utf8mb3 e utf8mb4, consulta Converting between 3-byte and 4-byte Unicode character sets nella documentazione di MySQL.

Output di esempio:

{
  "id": "utf8mb3",
  "title": "Usage of utf8mb3 charset",
  "status": "OK",
  "description": "Warning: The following objects use the deprecated utf8mb3 character set. It is recommended to convert them to use utf8mb4 instead, for improved Unicode support. The utf8mb3 character is subject to removal in the future.",
  "documentationLink": "https://dev.mysql.com/doc/refman/8.0/en/charset-unicode-utf8mb3.html",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "test.t1.col1",
        "description": "column's default character set: utf8",
        "dbObjectType": "Column"
      },
      {
        "level": "Warning",
        "dbObject": "test.t1.col2",
        "description": "column's default character set: utf8",
        "dbObjectType": "Column"
      }
  ]
}

Per risolvere il problema, è necessario creare nuovamente gli oggetti e le tabelle a cui si fa riferimento. Per ulteriori informazioni e prerequisiti prima di procedere, consulta Converting between 3-byte and 4-byte Unicode character sets nella documentazione di MySQL.

Livello di controllo preliminare: avviso

Valori zero in date, datetime e timestamp

MySQL ora applica regole più rigide per quanto riguardo l’uso di valori zero nelle colonne di date, datetime e timestamp. Si consiglia di utilizzare le modalità NO_ZERO_IN_DATE e NO_ZERO_DATE SQL insieme alla modalità strict, poiché verranno unite alla modalità strict in una futura versione di MySQL.

Se, al momento dell’esecuzione del controllo preliminare, l’impostazione sql_mode per una qualsiasi delle connessioni al database non include queste modalità, viene generato un avviso nel controllo preliminare. Gli utenti potrebbero comunque essere in grado di inserire valori di date, datetime e timestamp contenenti valori zero. Tuttavia, si consiglia vivamente di sostituire i valori zero con valori validi, poiché potrebbero avere un comportamento diverso in futuro e non funzionare correttamente. Poiché si tratta di un avviso, non impedisce l’esecuzione degli aggiornamenti, ma si consiglia di iniziare a pianificare le azioni necessarie.

Output di esempio:

{
  "id": "zeroDatesCheck",
  "title": "Zero Date, Datetime, and Timestamp values",
  "status": "OK",
  "description": "Warning: By default zero date/datetime/timestamp values are no longer allowed in MySQL, as of 5.7.8 NO_ZERO_IN_DATE and NO_ZERO_DATE are included in SQL_MODE by default. These modes should be used with strict mode as they will be merged with strict mode in a future release. If you do not include these modes in your SQL_MODE setting, you are able to insert date/datetime/timestamp values that contain zeros. It is strongly advised to replace zero values with valid ones, as they may not work correctly in the future.",
  "documentationLink": "https://lefred.be/content/mysql-8-0-and-wrong-dates/",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "global.sql_mode",
        "description": "does not contain either NO_ZERO_DATE or NO_ZERO_IN_DATE which allows insertion of zero dates"
      },
      {
        "level": "Warning",
        "dbObject": "session.sql_mode",
        "description": " of 10 session(s) does not contain either NO_ZERO_DATE or NO_ZERO_IN_DATE which allows insertion of zero dates"
      }
  ]
}

Livello di controllo preliminare: avviso

Verifica se la lunghezza dell’elenco della cronologia dei segmenti di rollback per il cluster è elevata

Come indicato in auroraUpgradeCheckForIncompleteXATransactions, durante l’esecuzione del processo di aggiornamento a una versione principale, è essenziale che venga eseguito un arresto pulito dell’istanza database Aurora MySQL versione 2. Ciò garantisce che tutte le transazioni vengano eseguite o ripristinate e che InnoDB abbia eliminato tutti i record del log di undo.

Se l’elenco della cronologia dei segmenti di rollback (HLL) del cluster di database ha una lunghezza elevata, il cluster può prolungare il tempo impiegato da InnoDB per completare l’eliminazione dei record del log di undo, con conseguenti tempi di inattività prolungati durante il processo di aggiornamento alla versione principale. Se il controllo preliminare rileva che l’HLL del cluster di database è elevata, genera un avviso. Sebbene ciò non impedisca il proseguimento dell’aggiornamento, ti consigliamo di monitorare attentamente l’HLL del tuo cluster di database. Mantenendola bassa, è possibile ridurre i tempi di inattività necessari per un aggiornamento a una versione principale. Per ulteriori informazioni sul monitoraggio dell’HLL, consulta La lunghezza dell'elenco della cronologia di InnoDB è aumentata in modo significativo.

Output di esempio:

{
  "id": "auroraUpgradeCheckForRollbackSegmentHistoryLength",
  "title": "Checks if the rollback segment history length for the cluster is high",
  "status": "OK",
  "description": "Rollback Segment History length is greater than 1M. Upgrade may take longer time.",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "information_schema.innodb_metrics",
        "description": "The InnoDB undo history list length('trx_rseg_history_len') is 82989114. Upgrade may take longer due to purging of undo information for old row versions."
      }
  ]
}

Il controllo preliminare restituisce un avviso perché ha rilevato che l’HLL di undo di InnoDB era elevata nel cluster di database (82989114). Sebbene l’aggiornamento proceda, a seconda della quantità di operazioni di undo da eliminare, i tempi di inattività necessari durante il processo di aggiornamento vengono prolungati.

Ti consigliamo di esaminare le transazioni aperte nel tuo cluster di database prima di eseguire l’aggiornamento nell’ambiente di produzione, per assicurarti che l’HLL rimanga di dimensioni gestibili.

Livello di controllo preliminare: avviso

Verifica se ci sono numerose modifiche alle righe di cui non è stato eseguito il commit

Come indicato in auroraUpgradeCheckForIncompleteXATransactions, durante l’esecuzione del processo di aggiornamento a una versione principale, è essenziale che venga eseguito un arresto pulito dell’istanza database Aurora MySQL versione 2. Ciò garantisce che tutte le transazioni vengano eseguite o ripristinate e che InnoDB abbia eliminato tutti i record del log di undo.

Se il cluster di database ha transazioni che hanno modificato un elevato numero di righe, può prolungare il tempo impiegato da InnoDB per completare un rollback della transazione nell’ambito del processo di arresto pulito. Se il controllo preliminare rileva transazioni di lunga durata, con un elevato numero di righe modificate nel cluster di database, genera un avviso. Sebbene ciò non impedisca il proseguimento dell’aggiornamento, ti consigliamo di monitorare attentamente le dimensioni delle transazioni attive del tuo cluster di database. Mantenendola bassa, è possibile ridurre i tempi di inattività necessari per un aggiornamento a una versione principale.

Output di esempio:

{
  "id": "auroraUpgradeCheckForUncommittedRowModifications",
  "title": "Checks if there are many uncommitted modifications to rows",
  "status": "OK",
  "description": "Database contains uncommitted row changes greater than 10M. Upgrade may take longer time.",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "information_schema.innodb_trx",
        "description": "The database contains 11000000 uncommitted row change(s) in 1 transaction(s). Upgrade may take longer due to transaction rollback."
      }
  ]
},

Il controllo preliminare segnala che il cluster di database contiene una transazione con 11.000.000 di modifiche alle righe senza commit, di cui dovrà essere eseguito il rollback durante il processo di arresto pulito. L’aggiornamento proseguirà, ma per ridurre i tempi di inattività durante il processo di aggiornamento, si consiglia di monitorare ed esaminare la situazione prima di eseguire l’aggiornamento sui cluster di produzione.

Per visualizzare le transazioni attive nell’istanza database di scrittura, puoi utilizzare la tabella information_schema.innodb_trx. La seguente query dell’istanza database di scrittura mostra le transazioni correnti, il tempo di esecuzione, lo stato e le righe modificate per il cluster di database.

# Example of uncommitted transaction
mysql> SELECT trx_started,
       TIME_TO_SEC(TIMEDIFF(now(), trx_started)) AS seconds_trx_has_been_running,
       trx_mysql_thread_id AS show_processlist_connection_id,
       trx_id,
       trx_state,
       trx_rows_modified AS rows_modified
FROM information_schema.innodb_trx;
+---------------------+------------------------------+--------------------------------+----------+-----------+---------------+
| trx_started         | seconds_trx_has_been_running | show_processlist_connection_id | trx_id   | trx_state | rows_modified |
+---------------------+------------------------------+--------------------------------+----------+-----------+---------------+
| 2024-08-12 18:32:52 |                         1592 |                          20041 | 52866130 | RUNNING   |      11000000 |
+---------------------+------------------------------+--------------------------------+----------+-----------+---------------+
1 row in set (0.01 sec)

# Example of transaction rolling back
mysql> SELECT trx_started,
       TIME_TO_SEC(TIMEDIFF(now(), trx_started)) AS seconds_trx_has_been_running,
       trx_mysql_thread_id AS show_processlist_connection_id,
       trx_id,
       trx_state,
       trx_rows_modified AS rows_modified
FROM information_schema.innodb_trx;
+---------------------+------------------------------+--------------------------------+----------+--------------+---------------+
| trx_started         | seconds_trx_has_been_running | show_processlist_connection_id | trx_id   | trx_state    | rows_modified |
+---------------------+------------------------------+--------------------------------+----------+--------------+---------------+
| 2024-08-12 18:32:52 |                         1719 |                          20041 | 52866130 | ROLLING BACK |      10680479 |
+---------------------+------------------------------+--------------------------------+----------+--------------+---------------+
1 row in set (0.01 sec)

Dopo il commit o il rollback della transazione, il controllo preliminare non restituisce più un avviso. Consulta la documentazione di MySQL e contatta il tuo team applicativo prima di eseguire il rollback di transazioni di grandi dimensioni, poiché il completamento del rollback può richiedere tempo, a seconda delle dimensioni delle transazioni.

{
  "id": "auroraUpgradeCheckForUncommittedRowModifications",
  "title": "Checks if there are many uncommitted modifications to rows",
  "status": "OK",
  "detectedProblems": []
},

Per ulteriori informazioni sull’ottimizzazione della gestione delle transazioni InnoDB e sul potenziale impatto dell’esecuzione e del rollback di transazioni di grandi dimensioni sulle istanze database MySQL, consulta Optimizing InnoDB transaction management nella documentazione di MySQL.

Livello di controllo preliminare: notifica

Utilizzo di flag sql_mode obsoleti

Oltre a MAXDB, altre opzioni sql_mode sono state rimosse: DB2, MSSQL, MYSQL323, MYSQL40, ORACLE, POSTGRESQL, NO_FIELD_OPTIONS, NO_KEY_OPTIONS e NO_TABLE_OPTIONS. A partire da MySQL 8.0, nessuno di questi valori può essere assegnato alla variabile di sistema sql_mode. Se questo controllo preliminare rileva sessioni aperte che utilizzano queste impostazioni sql_mode, assicurati che l’istanza database e i gruppi di parametri del cluster di database, nonché le applicazioni e le configurazioni client, siano aggiornati per disabilitarle. Per ulteriori informazioni, consulta la documentazione di MySQL.

Output di esempio:

{
  "id": "sqlModeFlagCheck",
  "title": "Usage of obsolete sql_mode flags",
  "status": "OK",
  "detectedProblems": []
}

Per risolvere questi errori di controllo preliminare, consulta maxdbFlagCheck.

Livello di controllo preliminare: errore, avviso o notifica

Problemi segnalati dal comando check table x for upgrade

Prima di avviare l’aggiornamento ad Aurora MySQL versione 3, check table for upgrade viene eseguito su ogni tabella degli schemi utente del cluster di database. Questo controllo preliminare non equivale a checkTableMysqlSchema.

Il comando check table for upgrade esamina le tabelle per individuare eventuali problemi che potrebbero verificarsi durante l’aggiornamento a una versione più recente di MySQL. L’esecuzione di questo comando prima di tentare un aggiornamento può aiutare a identificare e risolvere eventuali incompatibilità in anticipo, rendendo più agevole l’effettivo processo di aggiornamento.

Questo comando esegue diversi controlli su ogni tabella, come i seguenti:

A differenza di altri controlli preliminari, questo può restituire un errore, un avviso o una notifica a seconda dell’output di check table. Se questo controllo preliminare restituisce delle tabelle, esaminale attentamente insieme al messaggio e al codice restituito prima di iniziare l’aggiornamento. Per ulteriori informazioni, consulta CHECK TABLE statement nella documentazione di MySQL.

Vengono riportati un esempio di errore e un esempio di avviso.

Esempio di errore:

{
  "id": "checkTableOutput",
  "title": "Issues reported by 'check table x for upgrade' command",
  "status": "OK",
  "detectedProblems": [
      {
        "level": "Error",
        "dbObject": "test.parent",
        "description": "Table 'test.parent' doesn't exist"
      }
  ]
},

Il controllo preliminare segnala un errore che indica che la tabella test.parent non esiste.

Il file mysql-error.log per l’istanza database di scrittura mostra che c’è un errore di chiave esterna.

2024-08-13T15:32:10.676893Z 62 [Warning] InnoDB: Load table `test`.`parent` failed, the table has missing foreign key indexes. Turn off 'foreign_key_checks' and try again.
2024-08-13T15:32:10.676905Z 62 [Warning] InnoDB: Cannot open table test/parent from the internal data dictionary of InnoDB though the .frm file for the table exists.
Please refer to http://dev.mysql.com/doc/refman/5.7/en/innodb-troubleshooting.html for how to resolve the issue.

Accedi all’istanza database di scrittura ed esegui show engine innodb status\G per ottenere maggiori informazioni sull’errore della chiave esterna.

mysql> show engine innodb status\G
*************************** 1. row ***************************
  Type: InnoDB
  Name:
Status:
=====================================
2024-08-13 15:33:33 0x14ef7b8a1700 INNODB MONITOR OUTPUT
=====================================
.
.
.
------------------------
LATEST FOREIGN KEY ERROR
------------------------
2024-08-13 15:32:10 0x14ef6dbbb700 Error in foreign key constraint of table test/child:
there is no index in referenced table which would contain
the columns as the first columns, or the data types in the
referenced table do not match the ones in table. Constraint:
,
  CONSTRAINT `fk_pname` FOREIGN KEY (`p_name`) REFERENCES `parent` (`name`)
The index in the foreign key in table is p_name_idx
Please refer to http://dev.mysql.com/doc/refman/5.7/en/innodb-foreign-key-constraints.html for correct foreign key definition.
.
.

Il messaggio LATEST FOREIGN KEY ERROR segnala che il vincolo di chiave esterna fk_pname nella tabella test.child, che fa riferimento alla tabella test.parent, presenta un indice mancante o una mancata corrispondenza del tipo di dati. La documentazione di MySQL sui vincoli di chiave esterna spiega che le colonne a cui si fa riferimento in una chiave esterna devono avere un indice associato e che le colonne principale/secondaria devono utilizzare lo stesso tipo di dati.

Per verificare se il problema è correlato a un indice mancante o a una mancata corrispondenza del tipo di dati, accedi al database e controlla le definizioni della tabella disabilitando temporaneamente la variabile di sessione foreign_key_checks. Una volta fatto ciò, possiamo vedere che il vincolo secondario in questione (fk_pname) utilizza p_name varchar(20) CHARACTER SET latin1 DEFAULT NULL per fare riferimento alla tabella principale name varchar(20) NOT NULL. La tabella principale utilizza DEFAULT CHARSET=utf8, ma la colonna p_name della tabella secondaria utilizza latin1, quindi viene generato l’errore di mancata corrispondenza del tipo di dati.

mysql> show create table parent\G
ERROR 1146 (42S02): Table 'test.parent' doesn't exist

mysql> show create table child\G
*************************** 1. row ***************************
       Table: child
Create Table: CREATE TABLE `child` (
  `id` int(11) NOT NULL,
  `p_name` varchar(20) CHARACTER SET latin1 DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `p_name_idx` (`p_name`),
  CONSTRAINT `fk_pname` FOREIGN KEY (`p_name`) REFERENCES `parent` (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
1 row in set (0.00 sec)

mysql> set foreign_key_checks=0;
Query OK, 0 rows affected (0.00 sec)

mysql> show create table parent\G
*************************** 1. row ***************************
       Table: parent
Create Table: CREATE TABLE `parent` (
  `name` varchar(20) NOT NULL,
  PRIMARY KEY (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
1 row in set (0.00 sec)

mysql> show create table child\G
*************************** 1. row ***************************
       Table: child
Create Table: CREATE TABLE `child` (
  `id` int(11) NOT NULL,
  `p_name` varchar(20) CHARACTER SET latin1 DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `p_name_idx` (`p_name`),
  CONSTRAINT `fk_pname` FOREIGN KEY (`p_name`) REFERENCES `parent` (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
1 row in set (0.00 sec)

Per risolvere questo problema, possiamo modificare la tabella secondaria in modo che utilizzi lo stesso set di caratteri della tabella principale oppure modificare la tabella principale in modo che utilizzi lo stesso set di caratteri della tabella secondaria. In questo esempio, poiché la tabella secondaria utilizza esplicitamente latin1 nella definizione della colonna p_name, viene eseguito ALTER TABLE per modificare il set di caratteri in utf8.

mysql> alter table child modify p_name varchar(20) character set utf8 DEFAULT NULL;
Query OK, 0 rows affected (0.06 sec)
Records: 0  Duplicates: 0  Warnings: 0

mysql> flush tables;
Query OK, 0 rows affected (0.01 sec)

Una volta fatto ciò, il controllo preliminare viene superato e l’aggiornamento può procedere.

Esempio di avviso:

{
  "id": "checkTableOutput",
  "title": "Issues reported by 'check table x for upgrade' command",
  "status": "OK",
  "detectedProblems": [
      {
        "level": "Warning",
        "dbObject": "test.orders",
        "description": "Trigger test.orders.delete_audit_trigg does not have CREATED attribute."
      }
  ]
}

Il controllo preliminare segnala un avviso per il trigger delete_audit_trigg sulla tabella test.orders perché non ha un attributo CREATED. Secondo quanto riportato in Checking version compatibility nella documentazione di MySQL, questo messaggio è informativo e viene stampato per i trigger creati prima di MySQL 5.7.2.

Poiché si tratta di un avviso, non impedisce il proseguimento dell’aggiornamento. Tuttavia, se desideri risolvere il problema, puoi creare nuovamente il trigger in questione; una volta fatto ciò, il controllo preliminare ha esito positivo senza avvisi.

{
  "id": "checkTableOutput",
  "title": "Issues reported by 'check table x for upgrade' command",
  "status": "OK",
  "detectedProblems": []
},