就地升级数据库主要版本

MySQL   |  PostgreSQL   |  SQL Server

预览版 — PostgreSQL 18

此功能 受服务专用条款的约束。 您可按照云端数据处理附录的规定，针对 此功能 处理个人数据，但须遵守您据以访问 Google Cloud 的协议中所述的义务与限制。 非正式版功能“按原样”提供，且可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

本页面介绍了如何通过就地升级 Cloud SQL 实例而不是通过迁移数据来升级数据库主要版本。

简介

数据库软件提供商会定期发布包含新功能、性能改进和安全增强功能的新主要版本。Cloud SQL 会在新版本发布后进行提取。Cloud SQL 为新的主要版本提供支持后，您可以升级实例以使数据库保持最新。

您可以就地升级实例的数据库版本，也可以通过迁移数据。 就地升级是较简单的升级实例主要版本的方法。您无需迁移数据或更改应用连接字符串。通过就地升级，您可以在升级后保留当前实例的名称、IP 地址和其他设置。就地升级不需要移动数据文件，可以更快地完成。在某些情况下，停机时间比迁移数据所需的短。

Cloud SQL for PostgreSQL 就地升级操作使用 pg_upgrade 实用程序。

规划主要版本升级

1. 确认您拥有执行主要版本升级所需的角色：Cloud SQL Owner 或 Cloud SQL Admin。

2. 选择目标主要版本。

   gcloud

   如需了解如何安装和开始使用 gcloud CLI，请参阅安装 gcloud CLI。如需了解如何启动 Cloud Shell，请参阅使用 Cloud Shell。

   如需检查可进行就地升级的目标数据库版本，请执行以下操作：

   1. 运行以下命令：

   gcloud sql instances describe INSTANCE_NAME
      

   将 INSTANCE_NAME 替换为实例名称。

   2. 在命令的输出中，找到标记为 upgradableDatabaseVersions 的部分。
   3. 每个子部分都会返回一个可升级的数据库版本。在每个子部分中，请查看以下字段。
   • majorVersion：可进行就地升级的目标主要版本。
   • name：包含主要版本的数据库版本字符串。
   • displayName：数据库版本的显示名称。

   REST v1

   如需检查哪些目标数据库版本可进行主要版本就地升级，请使用 Cloud SQL Admin API 的 instances.get 方法。

   在使用任何请求数据之前，请先进行以下替换：

   • INSTANCE_NAME：实例名称。

   HTTP 方法和网址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   如需发送您的请求，请展开以下选项之一：

   curl（Linux、macOS 或 Cloud Shell）

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   执行以下命令：

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   执行以下命令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   您应该收到类似以下内容的 JSON 响应：

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   REST v1beta4

   如需检查哪些目标数据库版本可进行实例的主要版本就地升级，请使用 Cloud SQL Admin API 的 instances.get 方法。

   在使用任何请求数据之前，请先进行以下替换：

   • INSTANCE_NAME：实例名称。

   HTTP 方法和网址：

   GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

   如需发送您的请求，请展开以下选项之一：

   curl（Linux、macOS 或 Cloud Shell）

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   执行以下命令：

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   执行以下命令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   您应该收到类似以下内容的 JSON 响应：

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   如需查看 Cloud SQL 支持的数据库版本的完整列表，请参阅数据库版本和版本政策。

3. 请考虑每个数据库主要版本中提供的功能并解决不兼容问题。

   • PostgreSQL 18（预览版）

     注意： PostgreSQL 18 是新支持的版本。我们强烈建议您查看此版本中的更改，并在执行主要版本升级之前，彻底验证实例的准备情况。

   • PostgreSQL 17

   • PostgreSQL 16

   • PostgreSQL 15

   • PostgreSQL 14

   • PostgreSQL 13

   • PostgreSQL 12

   • PostgreSQL 11

   • PostgreSQL 10

   新的主要版本引入了不兼容的更改，可能需要您修改应用代码、架构或数据库设置。请先查看目标主要版本的版本说明，以确定您必须解决的不兼容问题，然后才能升级数据库实例。

4. 执行升级预检。

5. 通过试运行测试升级。

   在升级生产数据库之前，请先在测试环境中执行端到端升级流程的试运行。您可以克隆实例，创建用于测试升级过程的数据的相同副本。

   除了验证升级是否成功完成之外，运行测试还可以确保应用在升级后的数据库上按预期运行。

   注意：在运行主要版本升级之前，请确保有足够的磁盘空间。 如果您尚未启用存储空间自动扩容功能，请记下升级后的试运行实例使用的磁盘存储空间。这有助于确定升级前是否需要增加生产实例的存储空间容量。

6. 确定升级时间。

   升级要求实例在一段时间内不可用。计划在数据库活动较少的时间段内升级。

准备主要版本升级

在升级之前，请完成以下步骤。

1. 检查 template 和 postgres 数据库的 LC_COLLATE 值。每个数据库的字符集都必须是 en_US.UTF8。

   如果 template 和 postgres 数据库的 LC_COLLATE 值不是 en_US.UTF8，则主要版本升级将失败。如需解决此问题，如果任一数据库的字符集不是 en_US.UTF8，请在执行升级之前将 LC_COLLATE 值更改为 en_US.UTF8。

   如需更改数据库的编码，请执行以下操作：

   1. 转储数据库。
   2. 删除数据库。
   3. 使用不同的编码（在此示例中为 en_US.UTF8）创建新数据库。
   4. 重新加载数据。

   另一种方法是重命名数据库：

   1. 关闭与数据库的所有连接。
   2. 重命名数据库。
   3. 更新应用配置，以使用新的数据库名称。
   4. 使用默认编码创建一个新的空数据库。

   我们建议您先在克隆的实例上执行这些步骤，然后再将其应用于生产实例。

2. 管理其余的 PostgreSQL 扩展程序。

   大多数扩展程序适用于升级后的数据库主要版本。删除目标版本中不再受支持的任何扩展程序。例如，如果您要升级到 PostgreSQL 11 或更高版本，请删除 chkpass 扩展程序。

   您可以手动将 PostGIS 及其相关扩展程序升级到最新支持的版本。

   有时，如果从 PostGIS 2.x 版进行升级，可能会导致剩余数据对象未与 PostGIS 扩展程序关联的情况。这可能会阻止升级操作。 如需了解如何解决此问题，请参阅修复损坏的 postgis 光栅安装。

   有时，由于对象使用了已弃用的函数，因此升级到 PostGIS 3.1.7 版或更高版本无法完成。这可能会阻止升级操作。如需检查升级状态，请运行 SELECT PostGIS_full_version();。如果存在警告，请删除使用已弃用的函数的所有对象，并将 PostGIS 扩展程序更新到任何中间版本或更高版本。完成这些操作后，请再次运行 SELECT PostGIS_full_version(); 命令。验证是否未显示任何警告。然后，继续执行升级操作。

   如需详细了解如何升级 PostGIS 扩展程序，请参阅升级 PostGIS。如需了解与升级 PostGIS 相关的问题，请参阅检查 PostgreSQL 实例的版本。
3. 管理自定义数据库标志。检查您为 PostgreSQL 实例配置的任何自定义数据库标志的名称。如需了解与这些标志相关的问题，请参阅检查 PostgreSQL 实例的自定义标志。
4. 从一个主要版本升级到另一个主要版本时，请尝试连接到每个数据库，看看是否存在任何兼容性问题。确保数据库可以相互连接。检查每个数据库的 datallowconn 字段，确保允许建立连接。t 值表示允许，f 值表示无法建立连接。
5. 如果您使用 Datadog 安装将 Cloud SQL 实例升级到 PostgreSQL 10 或更高版本，请在执行升级之前丢弃 pg_stat_activity() 函数。

已知限制

以下限制会影响 Cloud SQL for PostgreSQL 的主要版本就地升级：

• 您不能对外部副本执行主要版本就地升级。
• 将具有超过 1,000 个数据库的实例从一个版本升级到另一个版本可能需要很长时间并超时。
• 使用 select * from pg_largeobject_metadata; 语句查询 Cloud SQL 实例的每个 PostgreSQL 数据库中的大型对象的数量。如果所有数据库的结果超过 1000 万个大型对象，则升级会失败。Cloud SQL 会回滚到数据库的先前版本。
• 在执行到 PostgreSQL 16 及更高版本的主要版本就地升级之前，请将所有数据库的 PostGIS 扩展程序升级到 3.4.0 版。对于 PostgreSQL 18，请升级到 PostGIS 版本 3.6.0。
• 在执行到 PostgreSQL 17 的主要版本就地升级之前，请将所有数据库的 rdkit 扩展程序升级到 4.6.1 版。
• 在执行到 PostgreSQL 16、17 或 18 的主要版本就地升级之前，请将所有数据库的 pg_squeeze 扩展程序分别升级到 1.6 版、1.7 版或 1.8 版。
• 如果您使用的是 PostgreSQL 9.6、10、11 或 12 版，则不支持 PostGIS 扩展程序 3.4.0 版。因此，如需执行到 PostgreSQL 16 及更高版本的主要版本就地升级，您必须先升级到 PostgreSQL 的中间版本（版本 13、14 或 15）。

• 如果您为实例安装了 pg_ivm 扩展程序，则无法执行主要版本升级。如需解决此问题，请卸载此扩展程序，然后执行升级。如需详细了解这些扩展程序，请参阅配置 PostgreSQL 扩展程序。

• 如果您启用了 vacuum_defer_cleanup_age 和 force_parallel_mode 标志，则无法执行主要版本升级。如需解决此问题，请删除这些标志，然后执行升级。如需详细了解这些标志（包括如何删除它们），请参阅配置数据库标志。

  注意：对于 PostgreSQL 16 及更高版本，vacuum_defer_cleanup_age 标志已弃用，force_parallel_mode 标志已重命名为 debug_parallel_query。

评估实例的升级准备情况

Cloud SQL 允许您在主要版本升级之前对实例运行预检。此预检查是一项长时间运行的操作 (LRO)，用于检查您的实例是否已准备好进行升级。它有助于在升级操作之前发现潜在问题，例如不兼容性、配置问题或数据问题。

预检查会确认您的实例是否可以升级，或者列出您需要先解决的问题及其解决方案。这些问题可能是由不兼容的扩展程序、不受支持的依赖项或数据格式问题引起的。

预检主要读取实例的元数据并执行检查。这些任务不会影响实例的性能，也不会导致停机。我们强烈建议您运行预检，因为这有助于防止升级失败和意外停机。

运行预检时，会发生以下情况之一：

• 未发现任何问题：预检已成功完成，未发现任何问题。
• 发现会阻碍升级的问题：预检已成功完成，但发现了一些会阻碍升级的错误。必须先解决这些问题，然后才能升级。
• 发现非阻塞警告：预检已成功完成，并发现了一些警告，但这些警告不会阻止升级。

根据预检结果，您可以继续升级，也可以先修复发现的问题，然后再升级。

限制

使用主要版本升级预检时，请考虑以下限制：

• 实例状态必须设置为 RUNNING。
• 该实例必须是主实例。预检不支持副本实例。

• 实例不得有任何待处理的阻塞性操作。如果存在待处理的阻塞操作，则预检会因以下消息而导致错误：

  Operation failed because another operation was already in progress. Try
  your request after the current operation is complete.
  

• 预检需要连接到实例上的所有数据库。如果数据库无法访问、处于锁定状态或无响应，预检可能会失败或显示错误。虽然预检不会影响实例的性能或导致停机，但我们建议在数据库负载较低时运行预检。

准备工作

• 确保已为您的实例启用 Cloud SQL Admin API。
• 确认您拥有 cloudsql.instances.preCheckMajorVersionUpgrade IAM 权限。

执行预检

如需执行主要版本升级预检，请执行以下操作：

gcloud

1. 运行预检查：

   gcloud sql instances pre-check-major-version-upgrade INSTANCE_NAME \
   --target-database-version=TARGET_DATABASE_VERSION \
   --project=PROJECT_ID \
   [--async]
   

   替换以下内容：

   • INSTANCE_NAME：实例的名称。
   • TARGET_DATABASE_VERSION：要将实例升级到的主要版本。如需查找数据库版本，请参阅规划升级。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。

2. 获取预检查操作名称：

   使用带有 --instance 标志的 gcloud sql operations list 命令：

   gcloud sql operations list --instance=INSTANCE_NAME
   

   替换以下内容：

   • INSTANCE_NAME：实例的名称。

3. 监控预检的状态。

   使用 gcloud sql operations describe 命令：

   gcloud sql operations describe OPERATION_NAME
   

   替换以下内容：

   • OPERATION_NAME：在上一步中检索到的预检操作名称。

REST v1

1. 运行预检。

   在使用任何请求数据之前，请先进行以下替换：

   • PROJECT_ID：项目 ID
   • INSTANCE_ID：实例 ID
   • TARGET_DATABASE_VERSION：要升级到的主要版本。如需查看可用数据库版本的列表，请参阅规划升级。

   HTTP 方法和网址：

   POST https://sqladmin.googleapis.com/sql/v1b/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

   请求 JSON 正文：

   {
     "preCheckMajorVersionUpgradeContext": {
       "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
     }
   }
   

   如需发送您的请求，请展开以下选项之一：

   curl（Linux、macOS 或 Cloud Shell）

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/sql/v1b/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade"

   PowerShell (Windows)

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/sql/v1b/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade" | Select-Object -Expand Content

   您应该收到类似以下内容的 JSON 响应：

   {
     "message": "Precheck description of finding",
     "message_type": "ERROR",
     "actions_required": [
       "Precheck action required to fix the finding"
     ]
   }
   

2. 获取预检查操作名称。

   将 PROJECT_ID 替换为项目的 ID 后，使用 GET 请求和 operations.list 方法。

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations
   

   替换以下内容：

   • PROJECT_ID：您的 Google Cloud 项目的 ID。

3. 监控预检的状态。

   使用 operations.list 方法发出 GET 请求：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME
   

   替换以下内容：

   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • OPERATION_NAME：上一步中检索到的预检操作名称。

REST v1beta4

1. 运行预检。

   在使用任何请求数据之前，请先进行以下替换：

   • PROJECT_ID：项目 ID
   • INSTANCE_ID：实例 ID
   • TARGET_DATABASE_VERSION：要升级到的主要版本。如需查看可用数据库版本的列表，请参阅规划升级。

   HTTP 方法和网址：

   POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

   请求 JSON 正文：

   {
     "preCheckMajorVersionUpgradeContext": {
       "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
     }
   }
   

   如需发送您的请求，请展开以下选项之一：

   curl（Linux、macOS 或 Cloud Shell）

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade"

   PowerShell (Windows)

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade" | Select-Object -Expand Content

   您应该收到类似以下内容的 JSON 响应：

   {
     "message": "Precheck description of finding",
     "message_type": "ERROR",
     "actions_required": [
       "Precheck action required to fix the finding"
     ]
   }
   

2. 获取预检查操作名称。

   将 PROJECT_ID 替换为项目的 ID 后，使用 GET 请求和 operations.list 方法。

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations
   

   替换以下内容：

   • PROJECT_ID：您的 Google Cloud 项目的 ID。

3. 监控预检的状态。

   使用 operations.list 方法发出 GET 请求：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME
   

   替换以下内容：

   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • operation_name：上一步中检索到的预检操作名称。

查看预检查发现结果

预检查完成后，您的实例要么已准备好升级，要么存在需要您注意的问题。

准备好进行升级

如果预检查成功完成且 preCheckResponse 数组为空，则表示未发现任何问题或警告。您的实例已准备好进行主要版本升级。如需继续，请参阅执行主要版本升级。

尚未准备好进行升级

如果预检查成功运行，但 preCheckResponse 数组包含问题，则表示您的实例尚未准备好进行升级，需要您注意。已发现的问题可能会也可能不会阻止升级。这些问题会在 preCheckResponse 中以以下消息类型进行记录：

类型	说明	屏蔽升级？
INFO	信息性消息。	否
WARNING	发现了一个潜在问题，但该问题不会阻碍升级。 Cloud SQL 建议您在升级之前查看并解决此警告，以确保完全兼容。	否
ERROR	发现了一个会阻止升级的严重问题。这些问题可能会导致升级失败。您必须先解决这些问题，然后才能升级实例。	是

如果您的实例仅包含 INFO 或 WARNING 消息，则可以升级该实例，但升级后可能会遇到问题。建议您先查看消息详情并解决问题，然后再升级。如果您的实例有 ERROR 条消息，您必须先解决这些问题，然后才能升级。

每种问题类型都包含 message 和 actions_required 字段。查看每个问题，了解其类型以及如何解决。如需详细了解常见问题及其解决方案，请参阅常见的主要版本升级预检错误。

解决问题后，重新运行预检以确认实例已准备好进行升级。然后，在预检通过后继续升级实例。

执行主要版本升级

注意： 仅支持使用 gcloud CLI 或 Cloud SQL API 将主要版本升级到 PostgreSQL 18。

您可以升级单个 Cloud SQL 实例的主要版本，也可以升级主实例的主要版本，并在升级过程中包含其所有副本（包括级联副本和跨区域副本）。

升级单个实例的主要版本

当您为单个实例启动升级操作时，Cloud SQL 会执行以下操作：

1. 检查实例的配置，以确保实例与升级兼容。
2. Cloud SQL 验证配置后，会将实例设为不可用。
3. 进行升级前备份。
4. 对实例执行升级。
5. 将实例设为可用。
6. 进行升级后备份。

注意：如果您使用读取副本，并且选择不在主要版本升级中包含副本，则必须在升级主实例之前升级读取副本。升级副本后，您无法回滚副本的数据库版本。只有在升级主实例后，升级后的副本的复制数据库才可用。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud SQL 实例页面。

   转到“Cloud SQL 实例”

2. 如需打开实例的概览页面，请点击实例名称。
3. 点击修改。
4. 在实例信息部分中，点击升级按钮并确认您想要进入升级页面。
5. 在选择数据库版本页面上，点击要升级到的数据库版本列表，然后选择一个可用的数据库主要版本。
6. 点击继续。
7. 在实例 ID 框中，输入实例的名称，然后点击开始升级按钮。

此操作需要几分钟才能完成。

验证升级后的数据库主要版本是否显示在实例概览页面上的实例名称下方。

gcloud

1. 开始升级。

   使用带有 --database-version 标志的 gcloud sql instances patch 命令。

   在运行该命令之前，请替换以下项：

   • INSTANCE_NAME：实例的名称。
   • DATABASE_VERSION：数据库主要版本的枚举（必须高于当前版本）。为主要版本指定一个可用作实例升级目标的数据库版本。您可以将此枚举作为规划升级的第一步来获取。如果您需要完整的数据库版本枚举列表，请参阅 SqlDatabaseEnums。

   gcloud sql instances patch INSTANCE_NAME \
   --database-version=DATABASE_VERSION

   主要版本升级需要几分钟才能完成。您可能会看到一条消息，指示操作所花的时间超出了预期。您可以忽略此消息，也可以运行 gcloud sql operations wait 命令来关闭该消息。

2. 获取升级操作名称。

   使用带有 --instance 标志的 gcloud sql operations list 命令。

   在运行命令之前，请将 INSTANCE_NAME 变量替换为实例名称。

   gcloud sql operations list --instance=INSTANCE_NAME

3. 监控升级的状态。

   使用 gcloud sql operations describe 命令。

   在运行该命令之前，请将 OPERATION 变量替换为上一步中检索到的升级操作名称。

   gcloud sql operations describe OPERATION

REST v1

1. 开始就地升级。

   将 PATCH 请求与 instances:patch 方法搭配使用。

   在使用任何请求数据之前，请先替换以下变量：

   • PROJECT_ID：项目的 ID。
   • INSTANCE_NAME：实例的名称。

   HTTP 方法和网址：

   PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   请求 JSON 正文：

   {
     "databaseVersion": DATABASE_VERSION
   }

   将 DATABASE_VERSION 替换为数据库主要版本的枚举（必须高于当前版本）。为主要版本指定一个可用作实例升级目标的数据库版本。您可以将此枚举作为规划升级的第一步来获取。如果您需要完整的数据库版本枚举列表，请参阅 SqlDatabaseVersion。

2. 获取升级操作名称。

   将 PROJECT_ID 替换为项目的 ID 后，使用 GET 请求和 operations.list 方法。

   HTTP 方法和网址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

3. 监控升级的状态。

   替换以下变量后，使用带有 operations.get 方法的 GET 请求：

   • PROJECT_ID：项目的 ID。
   • OPERATION_NAME：上一步中检索的升级操作名称。

   HTTP 方法和网址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

如需更新数据库版本，请使用 Terraform 资源和适用于 Google Cloud的 Terraform 提供程序 4.34.0 版或更高版本。

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

应用更改

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

1. 启动 Cloud Shell。

2. 设置要应用 Terraform 配置的默认 Google Cloud 项目。

   您只需为每个项目运行一次以下命令，即可在任何目录中运行它。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

1. 在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

   将示例代码复制到新创建的 main.tf 中。

   （可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。

3. 查看和修改要应用到您的环境的示例参数。
4. 保存更改。
5. 初始化 Terraform。您只需为每个目录执行一次此操作。

   terraform init

   （可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：

   terraform init -upgrade

应用更改

1. 查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：

   terraform plan

   根据需要更正配置。

2. 通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：

   terraform apply

   等待 Terraform 显示“应用完成！”消息。

3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

注意：Terraform 示例通常假定您的 Google Cloud 项目中启用了所需的 API。

删除更改

如需删除更改，请执行以下操作：

1. 如需停用防删除保护，请在 Terraform 配置文件中将 deletion_protection 参数设置为 false。

   deletion_protection =  "false"

2. 运行以下命令并在提示符处输入 yes，以应用更新后的 Terraform 配置：

   terraform apply

3. 通过运行以下命令并在提示符处输入 yes，移除之前使用 Terraform 配置应用的资源：

   terraform destroy

在您发出就地升级请求时，Cloud SQL 首先会执行升级前检查。如果 Cloud SQL 确定实例未准备好进行升级，则升级请求会失败，并显示一条消息来建议您如何解决问题。另请参阅排查主要版本升级问题。

注意：Cloud SQL 会自动在默认的次要版本上预配实例。

在主要版本升级中包含副本

如果主实例有副本，则可以在升级中包含所有副本。Cloud SQL 可以升级主实例的所有副本，包括跨区域副本和级联副本。

在主要版本升级中包含副本时，Cloud SQL 会执行以下操作：

1. 检查主实例和副本的配置，以确保实例和副本与升级兼容。
2. 将主实例设为不可用。
3. 进行主实例的升级前备份。
4. 停止所有副本的复制。
5. 对主实例执行升级。
6. 如果主实例的升级成功，则主实例会再次成为可用状态并重启复制。
7. Cloud SQL 会进行主实例的升级后备份。
8. Cloud SQL 会继续升级所有副本。

即使副本的主要版本升级失败，主实例仍会继续可用。

如需在主要版本升级中包含副本，您不能使用Google Cloud 控制台或 Terraform。您只能使用 gcloud CLI 或 Cloud SQL Admin API。

gcloud

1. 开始升级。

   将 gcloud sql instances patch 命令与 --database-version 和 --include-replicas-for-major-version-upgrade 标志结合使用。

   在运行该命令之前，请替换以下项：

   • INSTANCE_NAME：主实例的名称。
   • DATABASE_VERSION：数据库主要版本的枚举（必须高于当前版本）。为主要版本指定一个可用作实例升级目标的数据库版本。您可以将此枚举作为规划升级的第一步来获取。如果您需要完整的数据库版本枚举列表，请参阅 SqlDatabaseEnums。

   gcloud sql instances patch INSTANCE_NAME \
     --database-version=DATABASE_VERSION \
     --include-replicas-for-major-version-upgrade

   主要版本升级需要几分钟才能完成。您可能会看到一条消息，指示操作所花的时间超出了预期。您可以忽略此消息，也可以运行 gcloud sql operations wait 命令来关闭该消息。 升级副本可能需要几分钟才能完成。如需检查升级状态，请执行以下操作：

2. 获取升级操作名称。

   使用带有 --instance 标志的 gcloud sql operations list 命令。

   在运行命令之前，请将 INSTANCE_NAME 变量替换为实例名称。

   gcloud sql operations list --instance=INSTANCE_NAME

3. 监控升级的状态。

   使用 gcloud sql operations describe 命令。

   在运行该命令之前，请将 OPERATION 变量替换为上一步中检索到的升级操作名称。

   gcloud sql operations describe OPERATION

REST

1. 开始就地升级。

   将 PATCH 请求与 instances:patch 方法搭配使用。

   在使用任何请求数据之前，请先替换以下变量：

   • PROJECT_ID：项目的 ID。
   • INSTANCE_NAME：实例的名称。

   HTTP 方法和网址：

   PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   请求 JSON 正文：

   {
     "databaseVersion": DATABASE_VERSION
     "includeReplicasForMajorVersionUpgrade": true
   }

   • 将 DATABASE_VERSION 替换为数据库主要版本的枚举（必须高于当前版本）。为主要版本指定一个可用作实例升级目标的数据库版本。您可以将此枚举作为规划升级的第一步来获取。如果您需要完整的数据库版本枚举列表，请参阅 SqlDatabaseVersion。
   • 在 includeReplicasForMajorVersionUpgrade 字段中指定 true。

2. 获取升级操作名称。

   将 PROJECT_ID 替换为项目的 ID 后，使用 GET 请求和 operations.list 方法。

   HTTP 方法和网址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

3. 监控升级的状态。

   替换以下变量后，使用带有 operations.get 方法的 GET 请求：

   • PROJECT_ID：项目的 ID。
   • OPERATION_NAME：上一步中检索的升级操作名称。

   HTTP 方法和网址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

自动升级备份

执行主要版本升级时，Cloud SQL 会自动进行两个按需备份，称为升级备份：

• 第一个升级备份是升级前备份，它在开始升级之前立即进行。您可以使用此备份将数据库实例恢复为先前版本的状态。
• 第二个升级备份是升级后备份，该备份在允许对升级后的数据库实例执行新写入后立即创建。

查看备份列表时，系统会列出类型为 On-demand 的升级备份。升级备份会带有标签，以便您快速识别。例如，如果您要从 PostgreSQL 14 升级到 PostgreSQL 15，则升级前备份会标记为 Pre-upgrade backup, POSTGRES_14 to POSTGRES_15.，升级后备份会标记为 Post-upgrade backup, POSTGRES_14 to POSTGRES_15.

与其他按需备份一样，升级备份会一直保留，直到您删除它们或删除实例。如果您启用了 PITR，则无法在保留期限内删除升级备份。如果您需要删除升级备份，则必须停用 PITR，或等到升级备份不再位于保留期限内。

完成主要版本升级

完成主实例升级后，请执行以下步骤完成升级：

1. 刷新数据库统计信息。

   对主实例运行 ANALYZE 以在升级后更新系统统计信息。准确的统计信息可确保 PostgreSQL 查询规划器以最优方式处理查询。缺少统计信息可能会导致查询计划错误，进而可能会降低性能并占用过多内存。

2. 执行验收测试。

   运行测试可确保升级后的系统按预期运行。

排查主要版本升级问题

如果您尝试执行无效的升级命令（例如，如果实例包含新版本的无效数据库标志），则 Cloud SQL 会返回错误消息。

如果升级请求失败，请检查升级请求的语法。如果请求的结构有效，请尝试查看以下建议。

查看错误日志

如果有效升级请求出现任何问题，Cloud SQL 会将错误日志发布到 projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log。每个日志条目都包含标签，用于标识实例标识符，以帮助您识别升级错误的实例。 请查找此类升级错误并加以解决。

如需查看错误日志，请使用 Google Cloud控制台：

1. 在 Google Cloud 控制台中，前往 Cloud SQL 实例页面。

   转到“Cloud SQL 实例”

2. 如需打开实例的概览页面，请点击实例名称。

3. 在实例概览页面的操作和日志窗格中，点击查看 PostgreSQL 错误日志 (View PostgreSQL error logs) 链接。

   日志浏览器页面随即会打开。

4. 按以下方式查看日志：

   • 如需列出项目中的所有错误日志，请在日志名称日志过滤条件中选择日志名称。

   如需详细了解查询过滤条件，请参阅高级查询。

   • 如需过滤单个实例的升级错误日志，请在搜索所有字段框中输入以下查询，将 DATABASE_ID

   替换为项目 ID，后跟实例名称，格式为 project_id:instance_name。

   resource.type="cloudsql_database"
   resource.labels.database_id="DATABASE_ID"
   logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

   例如，如需按项目 buylots 中运行的名为 shopping-db 的实例过滤升级错误日志，请使用以下查询过滤条件：

    resource.type="cloudsql_database"
    resource.labels.database_id="buylots:shopping-db"
    logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

   您可以查看指定时间范围内报告的所有日志，也可以按严重程度过滤日志。一种常见的问题排查方法可能包括选择以下过滤条件：

   • 紧急
   • 提醒
   • 严重
   • 错误

带有 pg_upgrade_dump 前缀的日志条目表示发生了升级错误。例如：

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

此外，标有 .txt 辅助文件名的日志条目可能会列出您在尝试再次升级之前可能需要解决的其他错误。

所有文件名都可以在 postgres-upgrade.log 文件中找到。如需查找文件名，请查看 labels.FILE_NAME 字段。

可能包含要解决的错误的文件名包括：

• tables_with_oids.txt: 此文件包含使用对象标识符 (OID) 列出的表。请删除或修改表，使其不使用 OID。
• tables_using_composite.txt: 此文件包含使用系统定义的复合类型列出的表。请删除或修改表，使其不使用这些复合类型。
• tables_using_unknown.txt: 此文件包含使用 UNKNOWN 数据类型列出的表。请删除或修改表，使其不使用此数据类型。
• tables_using_sql_identifier.txt: 此文件包含使用 SQL_IDENTIFIER 数据类型列出的表。请删除或修改表，使其不使用此数据类型。
• tables_using_reg.txt: 此文件包含使用 REG* 数据类型（例如 REGCOLLATION 或 REGNAMESPACE）列出的表。请删除或修改表，使其不使用此数据类型。
• postfix_ops.txt: 此文件包含使用后缀（一元）运算符列出的表。请删除或修改表，使其不使用这些运算符。

检查内存

如果实例的共享内存不足，您可能会看到以下错误消息：ERROR: out of shared memory. 如果有 10,000 个表，则更有可能发生此错误。

在尝试升级之前，请将 max_locks_per_transaction 标志的值设置为实例中表数的大约两倍。更改此标志的值时，实例将重启。

检查连接容量

如果您的实例没有足够的连接容量，您可能会看到以下错误消息：ERROR: Insufficient connections.

Cloud SQL 建议您根据实例中的数据库数量增加 max_connections 标志值。更改此标志的值时，实例将重启。

检查是否存在模糊的列引用

Cloud SQL 会自动执行升级前检查，以识别依赖于系统目录视图（例如 pg_stat_activity 或 pg_stat_replication）的用户定义的视图。这些系统目录视图的列结构可能会在 PostgreSQL 主要版本之间发生变化。如果您的视图使用 select * 或依赖于这些系统视图的列顺序，那么在升级后，这些视图可能会变得不兼容，从而导致错误，例如 ERROR: column reference "column_name" is ambiguous。

升级前检查会通过检查依赖项来检测此类视图。如果发现不兼容的视图，升级过程会停止，并显示一条错误消息。此消息会列出每个数据库中需要解决的不兼容视图。

错误消息示例

• 对于与 pg_stat_activity 相关的问题：

  Please remove the following usages of views that depend on functions returning
  data types of pg_stat_activity before attempting an upgrade:
  (database: my_db, schema name: public, view name: my_stat_activity_view)

• 对于与 pg_stat_replication 相关的问题：

  Please remove the following usages of views that depend on functions returning
  data types of pg_stat_replication before attempting an upgrade:
  (database: my_db, schema name: public, view name: my_replication_stats_view)

如需解决此类问题并继续升级，请执行以下操作：1. 确定升级前检查错误消息中列出的视图。

1. 使用 DROP VIEW view_name; 删除这些视图。

2. 重试主要版本升级。

3. 升级完成后，重新创建这些视图。确保新视图定义与当前 PostgreSQL 版本中系统目录视图的架构兼容。您可能需要明确列出列，而不是使用 select *，以避免将来出现问题。

如需查看更详细的问题示例和进一步的分析洞见，请参阅此堆栈溢出讨论

检查 CASE 语句中是否存在 SRF

如果您要从版本 9.6 升级实例，并在 CASE 语句中使用集合返回函数，则可能会看到以下错误消息：ERROR: set-returning functions are not allowed in CASE。出现此问题是因为从版本 10 开始，不允许在 CASE 语句中使用集合返回函数。

如需解决此问题并成功升级实例，请确保在重试升级之前修改所有使用集合返回函数的 CASE 语句，以免使用这些函数。一些常用的 SRF 包括：

• unnest()
• generate_series()
• array_agg()
• regexp_split_to_table()
• jsonb_array_elements()
• json_array_elements()
• sonb_each()
• json_each()

检查对自定义类型转换创建的视图

如果您对自定义类型转换创建了视图，则系统会显示类似于以下内容的错误消息：ERROR: cannot cast type <type_1> to <type_2>。出现此问题的原因是自定义创建的类型转换存在权限问题。

如需解决此问题，请将您的实例更新为 [PostgreSQL version].R20240910.01_02

如需了解详情，请参阅自助维护。

检查事件触发器所有权

在 Cloud SQL 中，所有事件触发器都必须归具有 cloudsqlsuperuser 角色的用户所拥有。Cloud SQL 会执行升级前检查，以验证所有事件触发器的所有权。如果事件触发器由缺少 cloudsqlsuperuser 角色的用户所拥有，升级过程会停止，您可能会收到错误消息，例如：

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

如需解决此问题，请将事件触发器的所有者更改为具有 cloudsqlsuperuser 角色的用户（例如 postgres），或向当前所有者授予 cloudsqlsuperuser 角色。

如需识别其所有者缺少所需角色的事件触发器，请运行以下命令：

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

结果会显示其所有者没有 cloudsqlsuperuser 角色的任何事件触发器。

检查未记录的表中生成的列

如果您有一个未记录的表，其中包含生成的列，则可能会看到错误消息 ERROR: unexpected request for new relfilenumber in binary upgrade mode。出现此问题的原因是，表及其生成列的序列在持久性特征方面存在差异。

如需解决此问题，请执行以下操作：

1. 删除未记录的任何表：如果可能，请删除与生成的列相关联的所有未记录的表。请确保可以安全地缓解数据丢失问题，然后再继续操作。
2. 转换为永久表：暂时将未记录的表转换为永久表，具体步骤如下：
   1. 将表转换为已记录的表 ALTER TABLE SET LOGGED;
   2. 执行主要版本升级
   3. 将表还原为未记录的表 ALTER TABLE SET UNLOGGED

您可以使用以下查询来识别所有此类表：

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

检查 PostgreSQL 实例的自定义标志

如果要升级到 PostgreSQL 实例 14 版或更高版本，请检查为该实例配置的任何自定义数据库标志的名称。这是因为 PostgreSQL 为允许的自定义参数名称施加了额外限制。

自定义数据库标志的第一个字符必须是字母（A-Z 或 a-z）。所有后续字符可以是字母数字字符、下划线 (_) 特殊字符或美元符号 ($) 特殊字符。

移除扩展程序

如果您要升级 Cloud SQL 实例，则可能会看到以下错误消息：pg_restore: error: could not execute query: ERROR: role "16447" does not exist。

如需解决此问题，请按以下步骤操作：

1. 移除 pg_stat_statements 和 pgstattuple 扩展程序。
2. 执行升级。
3. 重新安装扩展程序。

长时间运行的 MVU 操作

与主要版本升级相关的底层任务有两项：

• 预检查操作：如果未在 3 小时内完成，则返回超时错误。
• 升级操作：如果未在六小时内完成，则返回超时错误。

如果实例的 MAJOR_VERSION_UPGRADE 操作持续时间超出预期，请调查 PostgreSQL 错误日志。这可能是由以下常见问题引起的：

• 大量表、视图或索引
• 资源（例如 CPU 或内存）不足
• 主要事务阻止数据库关闭，以便开始升级流程。您可以使用 Google Cloud 控制台检查当前进程。

常见的主要版本升级预检错误

主要版本升级预检发现的问题分为以下几类：

• 不兼容的扩展程序：这些是实例上与新主要版本不兼容的 Cloud SQL for PostgreSQL 扩展程序。

• 不受支持的依赖项：这些依赖项要么不受新主要版本支持，要么需要更新才能与新主要版本搭配使用。

• 数据库不兼容问题：这些是数据库或数据在主要版本升级后可能出现的问题。这包括数据库结构、数据类型、编码、排序规则或特定于新版本的系统目录更改方面的差异。

不兼容的扩展程序

下表列出了主要版本升级预检可能会发现的与不兼容的扩展程序相关的常见错误：

类型	错误示例	解决方法
不受支持或已弃用的扩展程序	Your installation contains unsupported extensions for the new version. These extensions must be removed before attempting an upgrade: (database: %s, Extension name: %s)	从使用 DROP EXTENSION $extension_name; 的所有数据库中移除扩展程序。
扩展程序版本不兼容	Your installation contains incompatible version extensions. These extensions must be upgraded to a compatible version before attempting an upgrade: (database: %s, Extension name: %s)	将扩展程序更新为与目标 Cloud SQL for PostgreSQL 版本兼容的版本。如需了解兼容版本，请参阅配置 Cloud SQL for PostgreSQL 扩展程序。
PostGIS 未打包的文件	PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade.	清理未打包的栅格文件。
PostGIS 个已弃用的函数	PostGIS version upgrade has not been completed, deprecated functions present. Please drop all objects using deprecated functions and upgrade to a different version of PostGIS before major version upgrade.	在升级 PostGIS 扩展程序之前，请先找到并移除或更改使用已弃用的 PostGIS 函数的所有数据库对象。
扩展程序所有权	Please ensure that the owner of the postgres_fdw extension has the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: my_db, extension name: postgres_fdw, owner: some_user)	使用 ALTER EXTENSION postgres_fdw OWNER TO postgres; 更改扩展程序所有者。

不受支持的依赖项

下表列出了主要版本升级预检可能会发现的与不受支持的依赖项相关的常见错误：

类型	错误示例	解决方法
事件触发器所有权	Please ensure that the owners of all event triggers have the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: your_db, triggerName your_trigger, owner: non_super_user)	使用 psql 或 Cloud SQL Studio 连接到已识别的数据库，并将触发器的所有者更改为 postgres 用户。
未提交的预处理语句	Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact)	提交或回滚准备好的语句。
已弃用的标志	flag "force_parallel_mode" is deprecated in new postgres version, Please delete this flag before retrying again	从实例配置中移除数据库标志。

数据库不兼容性

下表列出了主要版本升级预检可能会发现的与数据格式不兼容相关的常见错误：

类型	错误示例	解决方法
未知数据类型	Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column)	移除相应列或表，或使用 ALTER TABLE my_table ALTER COLUMN my_column TYPE TEXT; 更改表的数据类型。
reg* 数据类型	Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column)	移除相应列或更改其数据类型。
已移除的数据类型	Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ...	转换为 TEXT、timestamptz 或其他合适的数据类型。
​​aclitem 内部格式	Please remove the following usages of 'aclitem' data types before attempting an upgrade: ...	停止在数据库表定义中使用 aclitem。
系统定义的复合数据类型	Please remove the following usages of 'composite' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column)	将已识别的列更改为使用用户定义的复合类型或标准数据类型。系统复合类型在不同主要版本之间可能不一致。
包含 OIDS 的表格	Please remove the following usages of tables with OIDs before attempting an upgrade: (database: my_db, relation: my_table)	使用 ALTER TABLE my_table SET WITHOUT OIDS; 更新表格。
用户定义的 postfix 运算符	Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: my_db, operation id: 12345, operation namespace: public, operation name: !!, type namespace: public, type name: mytype)	移除自定义 postfix 运算符。您可能需要重写代码，改为使用前缀运算符或函数调用。
不兼容的多态函数	Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: my_db, object kind: function, object name: public.my_poly_func)	移除或更改函数，以移除不兼容的多态函数。这可能意味着需要调整函数签名或逻辑，以使其与 Cloud SQL for PostgreSQL 14 及更高版本兼容。
用户定义的编码转换	Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: my_db, namespace name: public, encoding conversions name: my_encoding_conv)	移除用户定义的编码转换。您可能需要在升级后重新创建该签名，以便与新版本搭配使用。
检查是否存在模糊的列引用	Cloud SQL 会自动检查依赖于系统目录视图的用户定义的视图。这些系统目录视图的列结构可能会在主要版本之间发生变化。 Please remove the following usages of views that depend on functions returning data types of pg_stat_activity before attempting an upgrade: (database: my_db, schema name: public, view name: my_stat_activity_view)	找到错误消息中列出的视图，然后使用 DROP VIEW 命令将其移除。升级后，重新创建这些视图。
包含生成的列或记录的序列的未记录的表	Please drop the following usages of 'Unlogged Tables with Logged Sequence' before attempting an upgrade: (database: your_db, table name: problematic_table)	您可以将表转换为 LOGGED，也可以使用 DROP TABLE 命令将其移除。在升级后重新创建表。
修复搜索路径为空的问题	Please update the search path of the 'll_to_earth' function (database: your_db, search path: )	earthdistance 扩展程序使用 earth 和 cube types，而未指定函数的搜索路径。使用 ALTER FUNCTION ll_to_earth SET search_path = public; 更新搜索路径。

将主实例恢复到先前的主要版本

如果升级后的数据库系统未按预期运行，您可能需要将主实例恢复到先前版本。您可以通过将升级前备份恢复到 Cloud SQL 恢复实例来执行此操作，该实例是运行升级前版本的新实例。

如需将主实例恢复到先前版本，请执行以下步骤：

1. 确定升级前备份。

   请参阅自动升级备份。

2. 创建恢复实例。

   使用升级前备份时 Cloud SQL 运行的主要版本创建新的 Cloud SQL 实例。设置与原始实例相同的标志和实例设置。

3. 恢复升级前备份。

   将升级前备份恢复到恢复实例。此命令可能需要几分钟才能完成。

4. 添加读取副本。

   如果您使用的是读取副本，请单独添加读取副本。

5. 连接您的应用。

   恢复数据库系统后，使用有关恢复实例及其读取副本的详细信息来更新应用。您可以继续在数据库的升级前版本上处理流量。

常见问题解答

升级数据库主要版本时，可能会出现以下问题。

实例在升级期间不可用吗？

可以。在 Cloud SQL 执行升级期间，您的实例在一段时间内不可用。

升级需要多长时间？

升级单个实例通常不到 10 分钟。 如果您的实例配置具有少量 vCPU 或内存，则升级可能需要更多时间。

如果您的实例托管过多数据库或表，或者您的数据库非常大，则升级可能需要几个小时，甚至超时，因为升级总时间与数据库中的对象数量相对应。如果您有多个实例需要升级，则升级时间会按比例增加。如果您在升级中包含副本，则升级操作最多可能需要一小时才能完成，具体取决于主实例具有的副本数量。

我可以监控升级过程的每个步骤吗？

Cloud SQL 可让您监控升级操作是否仍在进行中，但您无法跟踪每次升级中的各个步骤。

升级后是否可以取消？

不可以，升级一旦开始就无法取消。如果升级失败，Cloud SQL 会自动恢复您在先前版本上的实例。

升级期间，我的设置会发生什么情况？

执行主要版本就地升级时，Cloud SQL 会保留您的数据库设置，包括实例名称、IP 地址、明确配置的标志值和用户数据。但是，系统变量的默认值可能会发生变化。例如，PostgreSQL 13 及更低版本中 password_encryption 标志的默认值为 md5。升级到 PostgreSQL 14 后，此标志的默认值会更改为 scram-sha-256。

如需了解详情，请参阅配置数据库标志。如果目标版本中不再支持特定标志或值，则 Cloud SQL 会在升级期间自动移除该标志。

后续步骤

• 了解连接到实例的选项。
• 了解导入和导出数据。
• 详细了解如何 [设置数据库标志][flags]。