本页介绍了如何对 AlloyDB for PostgreSQL 集群执行数据库就地主要版本升级。如需了解数据库就地升级主要版本的使用场景、工作流和自动备份,请参阅数据库就地升级主要版本概览。
规划数据库主要版本升级
请按照以下步骤规划数据库主要版本升级:
查找当前的数据库主要版本。
控制台
在 Google Cloud 控制台中,前往集群页面。
从列表中选择一个集群。系统随即会显示概览页面。
在 Version 字段中找到数据库主要版本。
gcloud
如需了解如何安装和开始使用 gcloud CLI,请参阅安装 gcloud CLI。如需了解如何启动 Cloud Shell,请参阅使用 Cloud Shell。
运行以下命令可获取集群详细信息,包括当前的主要版本:
gcloud alloydb clusters describe CLUSTER_ID --region=REGION
进行以下替换:
- CLUSTER_ID:集群 ID
- REGION:集群位置或区域
REST v1beta
运行以下请求可获取集群详细信息,包括当前的主要版本:
GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID
进行以下替换:
- CLUSTER_ID:集群 ID
- PROJECT_ID:项目 ID
- REGION:集群位置或区域
如需发送请求,请使用以下选项之一:
curl(Linux、macOS 或 Cloud Shell)
执行以下命令:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ "https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID"
PowerShell (Windows)
运行以下命令:
$cred = gcloud auth print-access-token $headers = @{ "Authorization" = "Bearer $cred" } Invoke-WebRequest ` -Method GET ` -Headers $headers ` -Uri "https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID| Select-Object -Expand Content
从下表中确定目标数据库主要版本。如需查看 AlloyDB 支持的数据库版本的完整列表,请参阅数据库版本和版本政策。
来源主要版本 支持的主要目标版本 POSTGRES_14 POSTGRES_15 查看每个数据库主要版本中提供的功能。
确定您需要解决的任何不兼容问题。新的主要版本可能会引入不兼容的更改,您可能需要修改应用代码、架构或数据库设置。
在开始对生产集群进行主要版本升级之前,我们建议您克隆集群,并在克隆的集群上测试主要版本升级。
除了验证升级是否成功完成之外,运行测试还可以确保应用在升级后的集群上按预期运行。
为集群准备主要版本升级
如需完成需要连接到数据库的任何步骤,请使用 AlloyDB Studio、psql 或其他连接方法。
- 删除或提升跨区域副本。数据库就地升级主要版本不支持跨区域副本。如需了解详情,请参阅跨区域复制。
确保
postgres
和template1
数据库的编码和语言区域设置与template0
数据库相同。运行以下命令:
SELECT pg_encoding_to_char(encoding), datcollate, datctype FROM pg_database WHERE datname IN ('postgres', 'template1', 'template0');
如果
postgres
或template1
数据库的值与template0
数据库的值不同,则升级将失败。如需解决此问题,请按以下步骤操作:如果您的 AlloyDB 集群是逻辑复制源,请停用下游订阅并删除所有逻辑复制槽。升级后,您可以重新启用订阅并重新创建逻辑复制槽。如果 AlloyDB 实例只是逻辑复制目标,则不需要执行这些步骤。如需停用订阅并删除逻辑复制槽,请按以下步骤操作:
在订阅方或下游复制目标上停用每个下游订阅。请勿在要升级的 AlloyDB 实例上停用下游订阅:
如果您使用的是
pglogical
,请运行以下命令:SELECT * FROM pglogical.alter_subscription_disable(subscription_name, immediate);
将查询中的
subscription_name
替换为现有订阅名称。如果需要立即停用订阅,请将immediate
参数的值设置为true
。默认情况下,值为false
,并且订阅仅在当前事务结束后停用。例如:
postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub',true); alter_subscription_disable ---------------------------- t (1 row)
如果您使用的是
pglogical
以外的扩展程序,请运行以下命令:ALTER SUBSCRIPTION <subscription_name> DISABLE;
运行以下命令,在 AlloyDB 主实例上删除所有逻辑复制槽:
SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_type = 'logical';
管理您的 PostgreSQL 扩展程序。如需了解详情,请参阅配置数据库扩展。
升级前检查会检测扩展程序不兼容性,并在日志中显示这些违规情况以及建议的操作。如需了解详情,请参阅查看升级前检查失败情况。
您可能需要执行以下操作:
- 删除目标版本中不再受支持的任何扩展程序。
将 PostGIS 及其相关扩展程序(
address_standardizer
、address_standardizer_data_us
、postgis_raster
、postgis_sfcgal
、postgis_tiger_geocoder
和postgis_topology
)升级到目标 PostgreSQL 版本中受支持的版本。如需了解详情,请参阅 PostGIS 扩展程序。下表列出了每个 PostgreSQL 主要版本支持的最低 PostGIS 扩展程序版本:PostgreSQL 版本 PostGIS 支持的最低版本 PG14 3.1 PG15 3.2 例如,如果您的 PostGIS 版本为 3.1.x,并且您想从 POSTGRES 14 升级到 POSTGRES 15,请使用以下命令升级 PostGIS 扩展程序:
ALTER EXTENSION postgis UPDATE TO '3.2.3'; SELECT PostGIS_Version();
运行以下查询并检查每个数据库的
datallowconn
字段,验证是否允许对每个数据库(template0
除外)建立连接:SELECT datname,datallowconn from pg_database;
datallowconn
字段中的t
值表示允许连接。f
值表示无法建立连接。template0
数据库不得允许连接。如需允许连接到数据库,请运行以下命令:
ALTER DATABASE <database> WITH ALLOW_CONNECTIONS = true;
就地升级集群的主要版本
数据库就地升级主要版本可能需要 40 分钟到 48 小时才能完成,具体取决于数据库大小、架构大小和集群中的读取池实例数量等因素。主实例停机时间通常为 20 分钟到 1 小时,主要取决于您的数据库架构。
在您发出主要版本就地升级请求时,AlloyDB 首先会执行升级前检查。如果 AlloyDB 确定您的集群尚未准备好进行主要版本升级,则请求会失败。如需了解详情,请参阅排查主要版本就地升级问题。
如需就地升级数据库主要版本,请按以下步骤操作:
控制台
在 Google Cloud 控制台中,前往集群页面。
从列表中选择一个集群。系统随即会显示概览页面。
点击升级以开始数据库主要版本升级流程。
在选择数据库版本步骤中,选择一个可用的数据库主要版本作为目标主要版本。
点击继续。
在升级集群步骤的集群 ID 字段中,输入集群的名称。
点击开始升级。系统会将您定向至升级状态步骤,您可以在其中查看升级状态。如需了解详情,请参阅监控数据库主要版本升级。
gcloud
运行以下命令,开始主要版本就地升级:
gcloud alloydb beta clusters upgrade CLUSTER_ID --region=REGION --version=DATABASE_VERSION --async
以下是命令示例:
gcloud alloydb beta clusters upgrade my-cluster --region=us-central1 --version=POSTGRES_15 --async
REST v1beta
运行以下命令,开始主要版本就地升级:
PATCH https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:upgrade
请求 JSON 正文:
{
"version": "DATABASE_VERSION"
}
替换为目标数据库主要版本的枚举(必须高于当前版本)。
请求 JSON 正文示例:
{
"version": "POSTGRES_15"
}
监控集群主要版本升级
在原位升级数据库主要版本开始后,您可以使用 Google Cloud 控制台、gcloud CLI 或 REST API 监控升级状态。
控制台
如需在 Google Cloud 控制台中查看升级状态,请按以下步骤操作:
在 Google Cloud 控制台中,前往集群页面。
选择要升级的集群。系统随即会显示概览页面。
打开概览页面。
点击升级状态。系统随即会显示升级状态页面,您可以在其中查看升级状态。
gcloud
如需在 gcloud CLI 中查看升级状态,请按以下步骤操作:
运行以下命令来获取升级操作 ID。在运行该命令之前,请将
CLUSTER_ID
变量替换为集群名称:gcloud alloydb operations list --cluster=CLUSTER_ID --region=REGION_ID --filter=metadata.verb:upgrade
用于触发主要版本升级的 gcloud CLI 调用。
alloydb beta clusters upgrade
,以同步响应形式返回操作 ID。或者,结合使用gcloud alloydb operations list
命令和--cluster
标志。以下是命令示例:
gcloud alloydb operations list --cluster=my-cluster --region=us-central1 --filter=metadata.verb:upgrade
通过运行以下命令监控升级状态:
gcloud alloydb operations describe OPERATION_ID --region=REGION https://cloud.google.com/sdk/gcloud/reference/alloydb/operations/describe
REST v1beta
如需在 REST API 中查看升级状态,请按以下步骤操作:
获取升级操作 ID。
将以下
GET
请求与operations.list
方法结合使用,以列出所有升级操作并查找与目标集群对应的操作:GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/operations/filter=metadata.verb:upgrade
REST API 调用会将操作 ID 作为同步响应返回。
监控升级的状态。
将 GET 请求与
operations.get
方法搭配使用:GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID
进行以下替换:
- PROJECT_ID:项目 ID
- REGION:集群位置或区域
- OPERATION_ID:上一步中检索到的升级操作 ID。
以下是操作进行中的响应示例:
{ "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata", "createTime": "2024-09-16T23:17:39.727319438Z", "target": "projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID", "verb": "upgrade", "requestedCancellation": false, "apiVersion": "v1", "upgradeClusterStatus": { "state": "IN_PROGRESS", "cancellable": true, "stages": [ { "stage": "ALLOYDB_PRECHECK", "state": "IN_PROGRESS" }, { "stage": "PG_UPGRADE_CHECK", "state": "IN_PROGRESS" }, { "stage": "PREPARE_FOR_UPGRADE", "state": "NOT_STARTED" }, { "stage": "PRIMARY_INSTANCE_UPGRADE", "state": "NOT_STARTED" }, { "stage": "CLEANUP", "state": "NOT_STARTED" } ] } }, "done":false }
以下是操作完成后的示例响应:
{ "operations": [ { "metadata": { "@type": "type.googleapis.com/google.cloud.alloydb.v1betaalpha.OperationMetadata", "createTime": "2024-09-16T21:52:17.303861317Z", "endTime": "2024-09-16T22:29:13.947527949Z", "target": "projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID", "verb": "upgrade", "requestedCancellation": false, "apiVersion": "v1beta", "upgradeClusterStatus": { "state": "SUCCESS", "stages": [ { "stage": "ALLOYDB_PRECHECK", "state": "SUCCESS" }, { "stage": "PG_UPGRADE_CHECK", "state": "SUCCESS" }, { "stage": "PREPARE_FOR_UPGRADE", "state": "SUCCESS" }, { "stage": "PRIMARY_INSTANCE_UPGRADE", "state": "SUCCESS" }, { "stage": "CLEANUP", "state": SUCCESS" } ] } }, "response": { … }, "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID", "done": true } ] }
如需详细了解
response
结构,请参阅升级操作响应。
升级操作响应
UpgradeCluster
操作响应包含以下内容:
status
:整个升级操作的状态。可能的值包括SUCCESS
、FAILED
和PARTIAL_SUCCESS.
message
:提供升级操作结果的简要摘要。clusterUpgradeDetails
:要升级的集群的升级详情。此字段为数组。AlloyDB 仅允许一次集群升级,因此它必须只有一条条目。name
:集群的完全限定名称。upgradeStatus
:集群升级的状态。可能的值包括SUCCESS
、FAILED
、PARTIAL_SUCCESS
。PARTIAL_SUCCESS
表示一个或多个读取池实例无法升级。clusterType
:集群类型。AlloyDB 仅允许您升级单个PRIMARY
集群。此类型始终必须为PRIMARY
。databaseVersion
:集群的当前数据库版本。stageInfo
:核心升级阶段的相关信息。status
:SUCCESS
或FAILED
logs_url
:指向相应阶段生成的日志的链接。对于不会生成日志的阶段,此字段为空。
instanceUpgradeDetails
:集群中所有实例的升级信息。name
:实例的完全限定名称upgradeStatus
:SUCCESS
或FAILED
instanceType
:PRIMARY
或READ_POOL
以下是升级操作响应的示例:
"response": { "@type": "type.googleapis.com/google.cloud.alloydb.v1alpha.UpgradeClusterResponse", "status": "SUCCESS", "message": "Cluster upgraded successfully.", "clusterUpgradeDetails": [ { "name": "projects/1234/locations/us-central1/clusters/abc", "upgradeStatus": "SUCCESS", "clusterType": "PRIMARY", "databaseVersion": "POSTGRES_15", "stageInfo": [ { "stage": "ALLOYDB_PRECHECK", "status": "SUCCESS", "logsUrl": "https://console.cloud.google.com/logs/query..." }, { "stage": "PG_UPGRADE_CHECK", "status": "SUCCESS", "logsUrl": "https://console.cloud.google.com/logs/query..." }, { "stage": "PRIMARY_INSTANCE_UPGRADE", "status": "SUCCESS", "logsUrl": "https://console.cloud.google.com/logs/query..." }, { "stage": "READ_POOL_INSTANCES_UPGRADE", "status": "SUCCESS", } ], "instanceUpgradeDetails": [ { "name": "projects/1234/locations/us-central1/clusters/abc/instances/primary", "upgradeStatus": "SUCCESS", "instanceType": "PRIMARY", }, { "name": "projects/1234/locations/us-central1/clusters/abc/instances/read1", "upgradeStatus": "SUCCESS", "instanceType": "READ_POOL", }, { "name": "projects/1234/locations/us-central1/clusters/abc/instances/read2", "upgradeStatus": "SUCCESS", "instanceType": "READ_POOL", } ] } ] }
查看升级日志
AlloyDB 会将所有升级日志发布到 postgres_upgrade
日志名称。
如需查看升级相关日志,请按以下步骤操作:
-
在 Google Cloud 控制台中,转到 Logs Explorer 页面。
如果您使用搜索栏查找此页面,请选择子标题为 Logging 的结果。
选择
alloydb.googleapis.com/postgres_upgrade
作为日志名称。这会转换为查询"logName="projects/PROJECT_ID/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
。使用以下标签过滤日志:
标签 说明 LOG_TYPE
生成日志的升级阶段。可能的值包括 ALLOYDB_PRECHECK
、PG_UPGRADE_CHECK
和PG_UPGRADE
。OPERATION_NAME
升级操作的完整操作名称。 FILE_NAME
仅针对 pg_upgrade_check
和pg_upgrade
日志进行填充,并且与pg_upgrade
实用程序生成的日志文件相对应。
以下是返回给定操作的 AlloyDB 预检查升级日志的示例查询:
logName="projects/project1234/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
labels.LOG_TYPE="ALLOYDB_PRECHECK"
labels.OPERATION_NAME="projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID"
如需详细了解升级检查,请参阅数据库就地升级主要版本概览。
查看集群的升级日志
如果您不知道操作 ID 且操作已过期,如需查看集群的升级日志,请按以下步骤操作:
查询集群的 AlloyDB 预检查日志。
logName="projects/PROJECT_ID/logs/alloydb.googleapis.com%2Fpostgres_upgrade" labels.LOG_TYPE="ALLOYDB_PRECHECK" resource.labels.cluster_id=CLUSTER_ID
从
OPERATION_NAME
日志标签中查找Operation_ID
。在以下示例中,
OPERATION_NAME
中的Operation_ID
为operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013
。labels.OPERATION_NAME="projects/myproject/locations/us-central1/operations/operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013"
查询特定操作的所有
postgres_upgrade
日志。logName="projects/production-1/logs/alloydb.googleapis.com%2Fpostgres_upgrade" labels.OPERATION_NAME="operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013"
取消数据库就地升级主要版本
您可以通过 Google Cloud 控制台、gcloud CLI 或 REST API 取消正在进行的主要版本升级操作。
查找操作 ID
如需使用 gcloud CLI 或 REST API 取消主要版本升级操作,您需要操作 ID。您必须在 gcloud CLI 或 REST API 命令中指定此 ID,以便 AlloyDB 知道要取消的操作。
主实例升级到一定程度后,您将无法取消升级。
当您启动就地主要版本升级时,操作 ID 会在响应的 name
字段中返回。请参阅响应示例。
您还可以通过在 AlloyDB 集群上进行 operations.list
调用来查找操作 ID。
取消升级
如需取消就地升级主要版本,请按以下步骤操作:
控制台
在 Google Cloud 控制台中,前往集群页面。
从列表中选择一个集群。系统随即会显示概览页面。
点击升级 状态。
点击 Cancel。如果无法取消升级,此按钮会呈灰显状态。
gcloud
使用 gcloud alloydb operations cancel
命令可取消操作:
gcloud alloydb operations cancel OPERATION_ID
将 OPERATION_ID 变量替换为操作的 ID。
如果 gcloud alloydb operations cancel
命令的输出中 UpgradeClusterStatus
中的 cancellable
为 false
,AlloyDB 会忽略取消请求并继续升级。在这种情况下,API 不会抛出错误,而是会返回空响应。如需详细了解升级状态,请参阅监控集群主要版本升级。
REST v1beta
运行以下命令:
POST https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/operations/OPERATION_ID:cancel
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:项目 ID。
- OPERATION_ID:导入或导出操作的 ID。
如果 UpgradeClusterStatus
中的 cancellable
为 false
,则无法取消升级。
如需发送请求,请使用以下选项之一:
curl(Linux、macOS 或 Cloud Shell)
运行以下命令:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d "" \ "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel"
PowerShell (Windows)
运行以下命令:
$cred = gcloud auth print-access-token $headers = @{ "Authorization" = "Bearer $cred" } Invoke-WebRequest ` -Method POST ` -Headers $headers ` -Uri "https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/operations/OPERATION_ID/cancel"| Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
答案
此 REST API 调用不会返回任何响应。
完成主要版本就地升级
如需完成重大版本升级,请使用 AlloyDB Studio、psql 或其他连接方法连接到 AlloyDB 实例。
如果您使用的是非 AlloyDB 系统,请参阅系统文档了解连接说明。
升级集群后,请按照以下步骤完成升级:
如果您之前停用了
pglogical
,请重新启用pglogical
复制。启用pglogical
复制会自动创建所需的复制槽。使用以下命令删除目标副本上的
pglogical
订阅:select pglogical.drop_subscription(subscription_name name);
将
name
替换为现有订阅的名称。例如:postgres=> select pglogical.drop_subscription(subscription_name:= 'test_sub'); -[ RECORD 1 ]-----+-- drop_subscription |1
通过向 AlloyDB 主实例提供以下连接信息,在目标或副本上重新创建
pglogical
订阅:SELECT pglogical.create_subscription( subscription_name :='test_sub',<br> provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword' );
使用以下命令检查订阅的状态:
SELECT * FROM pglogical.show_subscription_status('test_sub');
通过执行写入事务并验证更改在目标位置是否可见来测试复制。
刷新数据库统计信息。
升级完成后,对主集群运行
ANALYZE
以更新系统统计信息。准确的统计信息可确保 PostgreSQL 查询规划器以最优方式处理查询。缺少统计信息可能会导致查询计划不准确,进而可能会降低性能并占用过多内存。运行验收测试,确保升级后的系统按预期运行。
验证升级后的数据库原位主要版本是否显示在 Google Cloud 控制台中集群的概览页面上。
恢复到先前的主要版本
如果升级后的数据库系统未按预期运行,您可能需要还原到升级前的状态。为此,您可以从升级前备份(AlloyDB 在升级过程中自动创建的备份或现有的升级前备份)进行恢复,以创建具有升级前状态的新集群。
如需恢复到升级前的状态,请按以下步骤操作:
确定要从中恢复的升级前备份。在升级过程中,AlloyDB 会自动创建前缀为
pre-upgrade-bkp
的升级前备份。如需了解详情,请参阅查看备份列表。从升级前的备份启动恢复,这会创建一个使用旧版 PostgreSQL 的集群。如需了解详情,请参阅从存储的备份恢复集群。
关联您的应用。使用有关已恢复集群及其读取副本的详细信息来更新应用。您可以继续在已恢复的集群上处理流量。
您还可以执行时间点恢复,将实例恢复到升级前的某个时间点。如需了解详情,请参阅使用时间点恢复 (PITR)。
限制
以下限制会影响 AlloyDB 的主要版本就地升级:
- 您无法对次要集群执行主要版本就地升级。
- 将具有超过 1,000 个数据库的实例从一个版本升级到另一个版本可能需要很长时间,并且升级可能会超时。
- AlloyDB 不支持升级使用
pg_largeobject_metadata
的集群。如果select count(*) from pg_largeobject_metadata;
不为零,则升级会失败。 - 就地升级主要版本操作可能会在升级前备份或升级后备份完成之前完成,尤其是当您拥有包含较少对象的大型数据库时。
- 升级后,在升级后的实例上重新开始写入与创建升级后备份之间可能会有短暂的延迟。这意味着,升级后的备份内容可能与升级前数据库中的内容不一致。
- 就地升级重大版本失败时,系统可能仍会创建升级前备份。
- 由于自动升级备份是连续备份,因此在达到连续备份和恢复的最大保留期限之前,您无法删除这些备份。达到最大保留期限后,系统会对备份进行垃圾回收;或者,您也可以使用 gcloud CLI 手动删除备份。如需了解详情,请参阅删除备份的限制。
后续步骤
- 详细了解数据库就地升级主要版本。
- 排查主要版本就地升级问题。
- 了解数据库就地升级主要版本错误。