When you run a precheck before upgrading an ApsaraDB RDS for MySQL instance to a new major engine version, the system checks multiple conditions and reports any blocking issues. This page explains each check item, what it looks for, why it fails, and how to fix it.
If you encounter an error not listed here, submit a ticket.
Check items
The table below covers all check items returned by the precheck. The supported upgrade paths are MySQL 5.6 → MySQL 5.7 and MySQL 5.7 → MySQL 8.0.
check_ins_major_version
Error message: The current engine version does not support this operation.
What it checks: Whether the instance version meets the prerequisites for a major engine version upgrade.
Cause: The instance is not running MySQL 5.6 or MySQL 5.7. Only upgrades from MySQL 5.6 to MySQL 5.7, or from MySQL 5.7 to MySQL 8.0, are supported.
Fix: See Prerequisites for a major engine version upgrade for the supported paths and requirements.
check_ins
Error message: The specified instance does not exist or is not supported.
What it checks: Whether the instance exists.
Cause: The instance was deleted or does not exist.
Fix: Verify that the target instance exists before running the precheck.
check_ins_status
Error message: The current DB instance state does not support this operation.
What it checks: Whether the instance is in the Running state.
Cause: Another operation is in progress—for example, an instance restart or network connection creation—so the instance is not in the Running state.
Fix: Wait for the current task to complete. After the instance returns to the Running state, initiate the precheck again.
check_master_ins
Error message: The current DB instance type does not support this operation.
What it checks: Whether the instance is a primary instance.
Cause: The instance is a disaster recovery instance or a read-only instance, not a primary instance.
Fix: Run the precheck on a primary instance.
check_ins_locked_state
Error message: The current DB instance lock mode does not support this operation.
What it checks: Whether the instance is locked.
Cause: The instance is in the Locking state.
Fix: Unlock the instance. After the instance status changes to Running, run the precheck again. For more information, see What do I do if my instance is in the Locking state?
check_maxscale_kernel
Error message: The Maxscale version of the instance is too low. Upgrade the Maxscale version first.
What it checks: Whether the database proxy's minor version is supported.
Cause: The instance uses a database proxy with a minor version earlier than 1.13.41.
Fix: Upgrade the proxy to a supported minor version, then retry the major engine version upgrade.
check_ins_tde_state
Error message: This instance is not configured with the specified TDE status.
What it checks: Whether transparent data encryption (TDE) is enabled.
Cause: TDE is enabled on the instance.
Fix: Instances with TDE enabled cannot be upgraded directly from the console. For the alternative upgrade procedure, see Upgrade the database version.
check_target_ins_level
Error message: The current DB instance class does not support this operation. (Error code: InvalidInstanceLevel.Malformed)
What it checks: Whether the current instance type is available for purchase.
Cause: The instance uses a phased-out instance type.
Fix: Change the instance to a currently available instance type, then retry the upgrade.
check_target_read_level
Error message: The read-only instance class is not supported in the target instance.
What it checks: Whether the read-only instance's instance type is available for purchase.
Cause: The read-only instance uses a phased-out instance type. This check applies to instances that use local SSDs.
Fix: Change the read-only instance to an available instance type, then run the precheck again.
To change the instance type, see Change the instance configuration.
To find available instance types, see Instance types for standard read-only instances or Instance types for Yitian read-only instances.
check_upgrade_check_task
Error message: The task already exists.
What it checks: Whether a precheck task is already running for this instance.
Cause: A major engine version upgrade precheck is already in progress.
Fix: Wait for the precheck to complete. After the instance status changes to Running, run the precheck again.
check_upgrade_task
Error message: The task already exists.
What it checks: Whether a major engine version upgrade task is already running for this instance.
Cause: A major engine version upgrade is already in progress.
Fix: Wait for the upgrade to complete. After the instance status changes to Running, run the precheck again.
check_storage_type
Error message: Standard SSDs do not support this operation. Please upgrade to ESSD.
What it checks: Whether the instance uses standard SSDs.
Cause: The instance uses standard SSDs.
Fix: Upgrade the storage type to ESSD (enterprise SSD), then retry the upgrade.
check_source_category
Error message: The specified source category is invalid.
What it checks: Whether the instance is on the Basic Edition or High-availability Edition.
Cause: The instance is on a different edition.
Fix: Major engine version upgrade prechecks are supported only for instances on the Basic Edition or High-availability Edition.
check_ins_biz_type
Error message: The specified business type is invalid.
What it checks: Whether the instance is a public cloud instance.
Cause: The instance is not a public cloud instance.
Fix: Major engine version upgrade prechecks are supported only for public cloud instances.
check_ins_tables_number
Error message: Upgrade not allowed due to an excessive number of tables: more than 1,000,000.
What it checks: The total number of tables on the instance.
Cause: The instance has more than 1,000,000 tables. This limit applies to both local SSDs and cloud disks.
Fix: Delete redundant tables before running the precheck.
check_ins_db_engine
Error message: The instance contains tables that use the MyISAM, Memory, TokuDB, Sphinx, or RocksDB engine.
What it checks: Whether any tables use a storage engine other than InnoDB.
Cause: The instance contains tables using MyISAM, Memory, TokuDB, Sphinx, or RocksDB. These storage engines are not supported for major engine version upgrades.
Fix: Convert all tables to InnoDB before upgrading. If the database already uses InnoDB but individual tables use other engines, run the following command for each affected table:
ALTER TABLE <table_name> engine=InnoDB;check_ins_fts
Error message: The current instance has a full-text index, and its minor version is earlier than 20221130.
What it checks: Whether the instance has full-text indexes created on the system tablespace.
Cause: In older versions of RDS for MySQL 5.6, full-text indexes are created on the system tablespace. During an upgrade, these indexes can corrupt the tablespace. This issue is fixed in RDS for MySQL 5.6 minor engine version 20221130, where full-text indexes are created on a separate tablespace.
Fix: Before upgrading from RDS for MySQL 5.6 to 5.7, clear any full-text indexes from the system tablespace.
Make sure the instance is running RDS for MySQL 5.6 minor engine version 20221130 or later. If it is not, upgrade to the latest RDS for MySQL 5.6 minor engine version first.
Drop the full-text index on the system tablespace. Use the table name shown in the error prompt.
ALTER TABLE $table_name DROP INDEX $fts_name;Recreate the full-text index.
ALTER TABLE $table_name ADD FULLTEXT INDEX $fts_name;Verify that no full-text indexes remain on the system tablespace. The following query returns any such indexes. An empty result means the precheck will not fail due to this issue.
SELECT NAME FROM information_schema.INNODB_SYS_TABLES WHERE TABLE_ID IN ( SELECT CONV(SUBSTRING_INDEX(SUBSTRING_INDEX(NAME, '_', -4),'_', 1),16,10) FROM INNODB_SYS_TABLES WHERE NAME LIKE '%fts_00000000%' AND SPACE = 0);
check_read_ins_number
Error message: The number of read-only instances cannot be greater than 8.
What it checks: The number of read-only instances for instances using local SSDs.
Cause: The instance has more than 8 read-only instances. This limit applies only to instances that use local SSDs.
Fix: Release the extra read-only instances. After the upgrade is complete, recreate them.
check_slave_state
Error message: The secondary node is unhealthy or has replication delays.
What it checks: The health and replication latency of the secondary node.
Cause: The secondary node is in an abnormal state or has a replication delay.
Fix: In the console, check the Node Replication Thread Status (seconds) and Node Replication Latency (seconds) monitoring metrics under Monitoring and alerts. Wait for the secondary node to return to normal, then run the precheck again.
check_account
Error message: The instance has an aliyun_root account.
What it checks: Whether an aliyun_root account exists on the instance.
Cause: A user manually created an aliyun_root account in RDS for MySQL 5.6. The aliyun_root account is a default system account in RDS for MySQL 5.7 and later. If it already exists in 5.6, the upgrade to 5.7 fails with a duplicate name error.
Fix: Delete or rename the manually created aliyun_root account before running the precheck. For information about system accounts, see System accounts.
check_sys_schema
Error message: The instance already has a sys database.
What it checks: Whether a sys database exists on the instance.
Cause: The sys database is created by default in RDS for MySQL 5.7. If it already exists in a 5.6 instance, the upgrade to 5.7 fails.
Fix: Rename the existing sys database. Because MySQL does not support RENAME DATABASE, run ALTER TABLE ... RENAME for each table individually.
To confirm whether the sys database exists, run:
SELECT * FROM information_schema.SCHEMATA WHERE SCHEMA_NAME='sys';check_table_discard
Error message: The instance contains discarded tables.
What it checks: Whether the instance has tables with discarded tablespaces (tables on which ALTER TABLE ... DISCARD TABLESPACE was run).
Cause: Discarded tables exist on the instance.
Fix: Query and delete the discarded tables.
SELECT space,name FROM INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES WHERE FS_BLOCK_SIZE=0 AND FILE_SIZE=0 AND name NOT LIKE '%#sql%';check_table_foreign_key
Error message: A partitioned table contains foreign keys.
What it checks: Whether any partitioned tables have foreign keys, or whether any partitioned tables are referenced by foreign keys of other tables.
Cause: A partitioned table contains a foreign key, or another table's foreign key references a partitioned table.
Fix: Resolve the conflicts between foreign keys and partitioned tables.
Query partitioned tables that contain foreign keys.
SELECT DISTINCT a.TABLE_SCHEMA, a.TABLE_NAME FROM information_schema.TABLE_CONSTRAINTS a, information_schema.PARTITIONS b WHERE a.CONSTRAINT_TYPE='FOREIGN KEY' AND a.TABLE_SCHEMA = b.TABLE_SCHEMA AND a.TABLE_NAME = b.TABLE_NAME AND (b.PARTITION_NAME IS NOT NULL OR b.SUBPARTITION_NAME IS NOT NULL);Query partitioned tables that are referenced by foreign keys of other tables.
SELECT DISTINCT a.TABLE_SCHEMA, a.TABLE_NAME, a.REFERENCED_TABLE_SCHEMA, a.REFERENCED_TABLE_NAME FROM information_schema.KEY_COLUMN_USAGE a, information_schema.PARTITIONS b WHERE a.REFERENCED_TABLE_SCHEMA = b.TABLE_SCHEMA AND a.REFERENCED_TABLE_NAME = b.TABLE_NAME AND (b.PARTITION_NAME IS NOT NULL OR b.SUBPARTITION_NAME IS NOT NULL);
check_column_length
Error message: One or more views have a column name with a length of 64 or more characters.
What it checks: Whether any views have column names of 64 or more characters.
Cause: MySQL does not support view column names with 64 or more characters.
Fix: Query the affected views, then delete them or shorten the column names.
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME IN (SELECT TABLE_NAME FROM INFORMATION_SCHEMA.VIEWS) AND CHAR_LENGTH(COLUMN_NAME) >= 64;check_foreign_key_constraint
Error message: One or more tables have a foreign key constraint name with a length greater than 64 characters.
What it checks: Whether any tables have foreign key constraint names longer than 64 characters.
Cause: Foreign key constraint names longer than 64 characters are not supported.
Fix: Query the affected tables, then delete or rename the foreign key constraints.
SELECT TABLE_SCHEMA, TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME IN (SELECT LEFT(SUBSTR(ID,INSTR(ID,'/')+1),INSTR(SUBSTR(ID,INSTR(ID,'/')+1),'_ibfk_')-1) FROM INFORMATION_SCHEMA.INNODB_SYS_FOREIGN WHERE CHAR_LENGTH(SUBSTR(ID,INSTR(ID,'/')+1))>64);check_dictionary_table
Error message: The MySQL 5.7 system database contains tables with names that conflict with the MySQL 8.0 data dictionary.
What it checks: Whether any tables in the MySQL 5.7 system database share names with tables used by the MySQL 8.0 data dictionary.
Cause: One or more tables in the MySQL 5.7 system database have names that conflict with the MySQL 8.0 data dictionary.
Fix: Query for conflicting table names, then delete or rename them.
SELECT TABLE_SCHEMA, TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE LOWER(
TABLE_SCHEMA) = 'mysql' and LOWER(TABLE_NAME) IN
('catalogs', 'character_sets', 'check_constraints', 'collations',
'column_statistics', 'column_type_elements', 'columns',
'dd_properties', 'events', 'foreign_key_column_usage', 'foreign_keys',
'index_column_usage', 'index_partitions', 'index_stats',
'indexes', 'parameter_type_elements', 'parameters', 'resource_groups', 'routines',
'schemata', 'st_spatial_reference_systems',
'table_partition_values', 'table_partitions', 'table_stats', 'tables',
'tablespace_files', 'tablespaces', 'triggers', 'view_routine_usage',
'view_table_usage');check_ins_health
Error message: The primary node of the instance is not available.
What it checks: Instance connectivity and availability.
Cause: Resources such as CPU or disk are fully utilized, making the primary node unavailable.
Fix: In the console, use the Monitoring and alerts feature to check whether all monitoring metrics are within normal ranges.
check_table_index_type
Error message: MySQL 8.0 does not support BTREE indexes on spatial data types.
What it checks: Whether any tables in MySQL 5.7 have BTREE indexes on spatial data type columns. This check applies only to upgrades to MySQL 8.0.
Cause: MySQL 8.0 does not support BTREE indexes on spatial data types (GEOMETRY, POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION).
Fix: Query the affected indexes, then delete or modify them.
SELECT DISTINCT s.* FROM INFORMATION_SCHEMA.STATISTICS s
INNER JOIN INFORMATION_SCHEMA.COLUMNS c
ON s.TABLE_SCHEMA = c.TABLE_SCHEMA
AND s.TABLE_NAME = c.TABLE_NAME
AND s.COLUMN_NAME = c.COLUMN_NAME
WHERE s.TABLE_SCHEMA NOT IN ('mysql', 'sys')
AND c.DATA_TYPE IN ('GEOMETRY', 'POINT', 'LINESTRING', 'POLYGON', 'MULTIPOINT',
'MULTILINESTRING', 'MULTIPOLYGON', 'GEOMETRYCOLLECTION')
AND s.INDEX_TYPE = 'BTREE';