Aurora MySQL 就地升级教程 - Amazon Aurora
查找升级失败的原因Aurora MySQL 就地升级的故障排除Aurora MySQL 版本 3 的升级后清理

Aurora MySQL 就地升级教程

以下 Linux 示例展示了如何使用 AWS CLI 执行就地升级过程的一般步骤。

第一个示例创建了运行 Aurora MySQL 版本 2.x 的 Aurora 数据库集群。该集群包括写入器数据库实例和读取器数据库实例。wait db-instance-available 命令会暂停，直到写入器数据库实例可用。此时，集群做好升级准备。

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

您可以将集群升级到的 Aurora MySQL 3.x 版本取决于集群当前正在运行的 2.x 版本和集群所在的 AWS 区域。第一个命令（带 --output text）只显示可用的目标版本。第二个命令显示响应的完整 JSON 输出。在该响应中，您可以看到详细信息，例如您用于 engine 参数的 aurora-mysql 值。您还可以看到这样一个事实，即升级到 3.02.0 表示主要版本升级。

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

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

此示例表示，如果您输入的目标版本号不是集群的有效升级目标，Aurora 不会执行升级。Aurora 也不会执行主要版本升级，除非您包含 --allow-major-version-upgrade 参数。这样一来，您就不能意外执行有可能需要大量测试和更改应用程序代码的升级。

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

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

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

集群和关联数据库实例的状态需要一段时间才能更改为 upgrading。集群和数据库实例的版本号仅在升级完成后才会更改。同样，您可以使用 wait db-instance-available 命令让写入器数据库实例等到升级完成后再继续。

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

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

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

此时，集群的版本号与为升级指定的版本号匹配。

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

8.0.mysql_aurora.3.02.0

前面的示例通过指定 --apply-immediately 参数进行了立即升级。为了让升级在集群预计不繁忙的方便之时进行，您可以指定 --no-apply-immediately 参数。这样做可以在集群的下一个维护时段内启动升级。维护时段定义了可以启动维护操作的时间段。在维护时段内，长时间运行的操作可能无法完成。因此，即使您预计升级可能需要很长时间，也不需要定义更大的维护时段。

以下示例升级最初运行 Aurora MySQL 版本 2.10.2 的集群。在 describe-db-engine-versions 输出中，False 和 True 值表示 IsMajorVersionUpgrade 属性。您可以从版本 2.10.2 升级到一些其他 2.* 版本。这些升级不被视为主要版本升级，因此不需要就地升级。就地升级仅适用于升级到列表中显示的 3.* 版本。

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

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

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


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

如果在没有指定的维护时段的情况下创建集群，Aurora 会随机选择一周中的一天。在这种情况下，modify-db-cluster 命令将在星期一提交。因此，我们将维护时段更改为星期二早上。所有时间都以 UTC 时区表示。tue:10:00-tue:10:30 时段对应于太平洋时间凌晨 2:00-2:30。维护时段的更改会立即生效。

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

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

以下示例说明如何获取升级所生成的事件的报告。--duration 参数表示检索事件信息的分钟数。系统需要此参数，因为默认情况下，describe-events 仅返回最后一个小时的事件。

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

查找升级失败的原因

在前面的教程中，从 Aurora MySQL 版本 2 升级到版本 3 已获成功。但是，如果升级失败，您会想知道原因。

您可以首先使用 describe-events AWS CLI 命令来查看数据库集群事件。此示例显示过去 10 小时 mydbcluster 的事件。

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

在本例中，我们遇到了升级预检查失败。

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

要诊断问题的确切原因，请检查写入器数据库实例的数据库日志。如果升级到 Aurora MySQL 版本 3 失败，写入器实例将包含一个名为 upgrade-prechecks.log 的日志文件。此示例说明了如何检测该日志是否存在，然后将其下载到本地文件以供检查。

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

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

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

upgrade-prechecks.log 文件为 JSON 格式。我们使用 --output text 选项下载该文件，避免在另一个 JSON 包装器中对 JSON 输出进行编码。对于 Aurora MySQL 版本 3 升级，此日志始终包含某些信息和警告消息。如果升级失败，日志仅包含错误消息。如果升级成功，则根本不会生成日志文件。

要汇总所有错误并显示关联的对象和描述字段，您可以对 upgrade-prechecks.log 文件的内容运行命令 grep -A 2 '"level": "Error"'。这样做会显示每个错误行及其后两行。其中包含相应数据库对象的名称以及有关如何解决问题的指导。

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

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

在此示例中，您可以对有问题的表运行以下 SQL 命令来尝试修复问题，也可以重新创建没有悬挂索引的表。

OPTIMIZE TABLE problematic_upgrade.dangling_fulltext_index;

然后重试升级。

Aurora MySQL 就地升级的故障排除

可以使用以下提示帮助排查 Aurora MySQL 就地升级问题。这些提示不适用于 Aurora Serverless 数据库集群。

就地升级被取消或减慢的原因 效果 允许在维护时段内完成就地升级的解决方案
尚未修补关联的 Aurora 跨区域副本 Aurora 取消升级。 升级 Aurora 跨区域副本并重试。
集群具有处于准备状态的 XA 事务 Aurora 取消升级。 提交或回滚所有准备好的 XA 事务。
集群正在处理数据定义语言 (DDL) 语句 Aurora 取消升级。 考虑等待并在所有 DDL 语句完成后执行升级。
集群有很多行未提交的更改 升级可能需要较长时间。

升级过程将回滚未提交的更改。这种情况的指示器为 TRX_ROWS_MODIFIED 表中的 INFORMATION_SCHEMA.INNODB_TRX 值。

考虑仅在提交或回退所有大型事务后才执行升级。
集群有大量的撤消记录 升级可能需要较长时间。

即使未提交的事务不会影响大量行，也可能涉及大量数据。例如，您可能正在插入大型 BLOB。Aurora 不会自动检测或生成此类事务活动的事件。这种情况的指示器为历史记录列表长度（HLL）。升级过程将回滚未提交的更改。

您可以在 SHOW ENGINE INNODB STATUS SQL 命令的输出中检查 HLL，也可以直接使用以下 SQL 查询进行检查：

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

还可以在 Amazon CloudWatch 中监控 RollbackSegmentHistoryListLength 指标。

考虑仅在 HLL 较小之后才执行升级。
集群正在提交大型二进制日志事务 升级可能需要较长时间。

升级过程将等到应用二进制日志更改时。在此期间，可能会启动更多事务或 DDL 语句，从而进一步减慢升级过程。

将升级过程安排在集群不忙于生成二进制日志复制更改的时间段。Aurora 不会自动检测或生成此情况的事件。
文件删除或损坏导致的模式不一致 Aurora 取消升级。

将临时表的原定设置存储引擎从 MyISAM 更改为 InnoDB。执行以下步骤：

  1. 将 default_tmp_storage_engine 数据库参数修改为 InnoDB。

  2. 重启数据库集群。

  3. 重启后，确认 default_tmp_storage_engine 数据库参数设置为 InnoDB。使用以下命令：

    show global variables like 'default_tmp_storage_engine';

  4. 确保不要创建任何使用 MyISAM 存储引擎的临时表。我们建议您暂停任何数据库工作负载，不要创建任何新的数据库连接，因为您即将升级。

  5. 再次尝试就地升级。
已删除主用户 Aurora 取消升级。
重要

不要删除主用户。

但是，如果由于某种原因您碰巧删除了主用户，请使用以下 SQL 命令将其还原：

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

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

有关对导致升级预检查失败的问题进行故障排除的更多详细信息，请参阅以下博客：

您可以使用以下步骤对上表中的某些条件执行自己的检查。这样，您可以在知道数据库处于可以成功快速地完成升级的状态时安排升级。

  • 您可以通过执行 XA RECOVER 语句来检查未完成的 XA 事务。然后，您可以在开始升级之前提交或回滚 XA 事务。

  • 您可以通过执行 SHOW PROCESSLIST 语句并在输出中查找 CREATE、DROP、ALTER、RENAME 和 TRUNCATE 语句来检查 DDL 语句。在开始升级之前，等待所有 DDL 语句完成。

  • 您可以通过查询 INFORMATION_SCHEMA.INNODB_TRX 表来检查未提交的行总数。该表为每个事务包含一行。TRX_ROWS_MODIFIED 列包含事务修改或插入的行数。

  • 您可以通过执行 SHOW ENGINE INNODB STATUS SQL 语句并在输出中查找 History list length 来检查 InnoDB 历史记录列表的长度。您还可以通过运行以下查询直接检查值：

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

    历史记录列表的长度对应于数据库为实施多版本并发控制 (MVCC) 而存储的撤消信息量。

Aurora MySQL 版本 3 的升级后清理

将任何 Aurora MySQL 版本 2 集群升级到 Aurora MySQL 版本 3 后，您可以执行以下其他清理操作：

  • 为任何自定义参数组创建与 MySQL 8.0 兼容的新版本。将所有必要的自定义参数值应用于新参数组。

  • 更新任何 CloudWatch 告警、设置脚本等，以便对名称受到包含性语言更改影响的任何指标使用新名称。有关此类指标的列表，请参阅 Aurora MySQL 版本 3 的包容性语言更改。

  • 更新任何 AWS CloudFormation 模板，以对名称受到包含性语言更改影响的任何配置参数使用新名称。有关此类参数的列表，请参阅 Aurora MySQL 版本 3 的包容性语言更改。

空间索引

升级到 Aurora MySQL 版本 3 后，检查是否需要删除或重新创建与空间索引相关的对象和索引。在 MySQL 8.0 之前，Aurora 可以使用不包含空间资源标识符 (SRID) 的索引来优化空间查询。Aurora MySQL 版本 3 仅使用包含 SRID 的空间索引。在升级过程中，Aurora 会自动删除任何没有 SRID 的空间索引，并在数据库日志中打印警告消息。如果观察到此类警告消息，请在升级后使用 SRID 创建新的空间索引。有关 MySQL 8.0 中空间函数和数据类型更改的更多信息，请参阅 MySQL 参考手册中的 MySQL 8.0 中的变化。