本页面介绍了如何通过就地升级 Cloud SQL 实例而不是通过迁移数据来升级数据库主要版本。
简介
数据库软件提供商会定期发布包含新功能、性能改进和安全增强功能的新主要版本。Cloud SQL 会在新版本发布后进行提取。Cloud SQL 为新的主要版本提供支持后,您可以升级实例以使数据库保持最新。
您可以就地升级实例的数据库版本,也可以迁移数据。就地升级是较简单的升级实例主要版本的方法。您无需迁移数据或更改应用连接字符串。通过就地升级,您可以在升级后保留当前实例的名称、IP 地址和其他设置。就地升级不需要移动数据文件,可以更快地完成。在某些情况下,停机时间比迁移数据所需的短。
Cloud SQL for PostgreSQL 就地升级操作使用pg_upgrade
实用程序。规划主要版本升级
选择目标主要版本。
请参阅 Cloud SQL 支持的版本列表。
请考虑每个数据库主要版本中提供的功能并解决不兼容问题。
新的主要版本引入了不兼容的更改,可能需要您修改应用代码、架构或数据库设置。请先查看目标主要版本的版本说明,以确定您必须解决的不兼容问题,然后才能升级数据库实例。
通过试运行测试升级。
在升级生产数据库之前,请先在测试环境中执行端到端升级流程的试运行。您可以克隆实例,创建用于测试升级过程的数据的相同副本。
除了验证升级是否成功完成之外,运行测试还可以确保应用在升级后的数据库上按预期运行。
确定升级时间。
升级要求实例在一段时间内不可用。计划在数据库活动较少的时间段内升级。
准备主要版本升级
在升级之前,请完成以下步骤。
-
检查
template
和postgres
数据库的LC_COLLATE
值。每个数据库的字符集都必须是en_US.UTF8
。如果
template
和postgres
数据库的LC_COLLATE
值不是en_US.UTF8
,则主要版本升级将失败。如需解决此问题,如果任一数据库的字符集不是en_US.UTF8
,请在执行升级之前将LC_COLLATE
值更改为en_US.UTF8
。如需更改数据库的编码,请执行以下操作:
- 转储数据库。
- 删除数据库。
- 使用不同的编码(在此示例中为
en_US.UTF8
)创建新数据库。 - 重新加载数据。
管理您的读取副本。
Cloud SQL for PostgreSQL 不支持跨版本复制,这意味着,当主实例复制到读取副本时,您无法升级主实例。在升级之前,请为每个读取副本停用复制功能或删除读取副本。
- 如果 Cloud SQL 是逻辑复制源,请按如下方式停用
pglogical
扩展程序复制。您可以在升级后重新启用它。如果 Cloud SQL 是逻辑复制目标,则不需要执行这些步骤。- 停用订阅,并使用以下命令断开副本与提供商之间的连接:
SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);
将
name
替换为现有订阅的名称。如果需要立即停用订阅,请将
immediate
参数的值设置为true
。默认情况下,值为false
,并且订阅仅在当前事务结束后停用。例如:
postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub', true); alter_subscription_disable ---------------------------- t (1 row)
- 通过连接到发布者或 Cloud SQL 主实例并运行以下命令来删除复制槽:
SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);
例如:
postgres=> SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots postgres-> WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots); -[ RECORD 1 ]------------+- pg_drop_replication_slot | postgres=>
- 停用订阅,并使用以下命令断开副本与提供商之间的连接:
管理其余的 PostgreSQL 扩展程序。
大多数扩展程序适用于升级后的数据库主要版本。删除目标版本中不再受支持的任何扩展程序。例如,如果您要升级到 PostgreSQL 11 或更高版本,请丢弃
chkpass
扩展程序。您可以将 PostGIS 及其相关扩展程序手动升级到最新支持的版本。如果您的 PostGIS 版本低于 3.1,请使用以下命令升级 PostGIS 扩展程序:
有时,如果从 PostGIS 2.x 版进行升级,可能会导致剩余数据对象未与 PostGIS 扩展程序关联的情况。这可能会阻止升级操作。如需了解如何解决此问题,请参阅修复损坏的 postgis 光栅安装。 如需详细了解如何升级 PostGIS 扩展程序,请参阅升级 PostGIS。如需了解与升级 PostGIS 相关的问题,请参阅检查 PostgreSQL 实例的版本。ALTER EXTENSION postgis UPDATE TO '3.1.7';
- 管理自定义数据库标志。检查您为 PostgreSQL 实例配置的任何自定义数据库标志的名称。如需了解与这些标志相关的问题,请参阅检查 PostgreSQL 实例的自定义标志。
- 从一个主要版本升级到另一个主要版本时,请尝试连接到每个数据库,看看是否存在任何兼容性问题。确保数据库可以相互连接。检查每个数据库的
datallowconn
字段,确保允许建立连接。t
值表示允许,f
值表示无法建立连接。 - 如果您使用 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 会回滚到先前版本的数据库。
就地升级数据库主要版本
启动升级操作时,Cloud SQL 首先会检查实例的配置,以确保实例与升级兼容。验证配置后,Cloud SQL 会将实例设为不可用,进行升级前备份,执行升级,使实例可用,然后在升级后进行备份。
控制台
-
在 Google Cloud 控制台中,转到 Cloud SQL 实例页面。
- 如需打开实例的概览页面,请点击实例名称。
- 点击修改。
- 在实例信息部分中,点击升级按钮并确认您想要进入升级页面。
- 在选择数据库版本页面上,点击要升级到的数据库版本列表,然后选择一个可用的数据库主要版本。
- 点击继续。
- 在实例 ID 框中,输入实例的名称,然后点击开始升级按钮。
验证升级后的数据库主要版本是否显示在实例概览页面上的实例名称下方。
gcloud
开始升级。
使用带有
--database-version
标志的gcloud sql instances patch
命令。在运行该命令之前,请替换以下项:
- INSTANCE_NAME:实例的名称。
- DATABASE_VERSION:数据库主要版本的枚举(必须高于当前版本)。请参阅可用的数据库版本枚举。
gcloud sql instances patch INSTANCE_NAME \ --database-version=DATABASE_VERSION
主要版本升级需要几分钟才能完成。您可能会看到一条消息,指示操作所花的时间超出了预期。您可以忽略此消息,也可以运行
gcloud sql operations wait
命令来关闭该消息。获取升级操作名称。
使用带有
--instance
标志的gcloud sql operations list
命令。在运行命令之前,请将 INSTANCE_NAME 变量替换为实例名称。
gcloud sql operations list --instance=INSTANCE_NAME
监控升级的状态。
使用
gcloud sql operations describe
命令。在运行该命令之前,请将 OPERATION 变量替换为上一步中检索到的升级操作名称。
gcloud sql operations describe OPERATION
REST v1
开始就地升级。
将 PATCH 请求与
instances:patch
方法搭配使用。在使用任何请求数据之前,请先替换以下变量:
- project_id:项目的 ID。
- instance_name:实例的名称。
HTTP 方法和网址:
POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance_name
请求 JSON 正文:
{ "databaseVersion": enum DATABASE_VERSION }
将 DATABASE_VERSION 替换为数据库主要版本的枚举(必须高于当前版本)。请参阅可用的数据库版本枚举。
使用 curl 或 PowerShell 发送请求。请参阅修改实例。
获取升级操作名称。
将 project_id 替换为项目的 ID 后,使用 GET 请求和
operations.list
方法。HTTP 方法和网址:
GET https://sqladmin.googleapis.com/v1/projects/project-id/operations
监控升级的状态。
替换以下变量后,使用带有
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 版或更高版本。
应用更改
如需在 Google Cloud 项目中应用 Terraform 配置,请完成以下部分中的步骤。
准备 Cloud Shell
- 启动 Cloud Shell。
-
设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。
您只需为每个项目运行一次以下命令,即可在任何目录中运行它。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
如果您在 Terraform 配置文件中设置显式值,则环境变量会被替换。
准备目录
每个 Terraform 配置文件都必须有自己的目录(也称为“根模块”)。
-
在 Cloud Shell 中,创建一个目录,并在该目录中创建一个新文件。文件名必须具有
.tf
扩展名,例如main.tf
。在本教程中,该文件称为main.tf
。mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
如果您按照教程进行操作,可以在每个部分或步骤中复制示例代码。
将示例代码复制到新创建的
main.tf
中。(可选)从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段,则建议这样做。
- 查看和修改要应用到您的环境的示例参数。
- 保存更改。
-
初始化 Terraform。您只需为每个目录执行一次此操作。
terraform init
(可选)如需使用最新的 Google 提供程序版本,请添加
-upgrade
选项:terraform init -upgrade
应用更改
-
查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期:
terraform plan
根据需要更正配置。
-
通过运行以下命令并在提示符处输入
yes
来应用 Terraform 配置:terraform apply
等待 Terraform 显示“应用完成!”消息。
- 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源,以确保 Terraform 已创建或更新它们。
删除更改
如需删除更改,请执行以下操作:
- 如需停用删除防护,请在 Terraform 配置文件中将
deletion_protection
参数设置为false
。deletion_protection = "false"
- 运行以下命令并在提示符处输入
yes
,以应用更新后的 Terraform 配置:terraform apply
-
通过运行以下命令并在提示符处输入
yes
,移除之前使用 Terraform 配置应用的资源:terraform destroy
在您发出就地升级请求时,Cloud SQL 首先会执行升级前检查。如果 Cloud SQL 确定实例未准备好进行升级,则升级请求会失败,并显示一条消息来建议您如何解决问题。另请参阅排查主要版本升级问题。
自动升级备份
执行主要版本升级时,Cloud SQL 会自动进行两个按需备份,称为升级备份:
- 第一个升级备份是升级前备份,它在开始升级之前立即进行。您可以使用此备份将数据库实例恢复为先前版本的状态。
- 第二个升级备份是升级后备份,该备份在允许对升级后的数据库实例执行新写入后立即创建。
查看备份列表时,系统会列出类型为 On-demand
的升级备份。升级备份会带有标签,以便您轻松识别。
例如,如果您要从 PostgreSQL 9.6 升级到 PostgreSQL 13,则升级前备份标记为 Pre-upgrade backup, POSTGRES_9_6 to POSTGRES_13.
,升级后备份 Post-upgrade backup, POSTGRES_13 from
POSTGRES_9_6.
与其他按需备份一样,升级备份会一直保留,直到您删除它们或删除实例。如果您启用了 PITR,则无法在保留期限内删除升级备份。如果您需要删除升级备份,则必须停用 PITR,或等到升级备份不再位于保留期限内。
完成主要版本升级
完成主实例升级后,请执行以下步骤完成升级:
- 如果您的实例在升级之前使用了
pglogical
复制,请启用这种复制功能。此操作将自动创建必要的复制槽。- 使用以下命令删除目标副本上的
pglogical
订阅:select pglogical.drop_subscription(subscription_name name);
将
name
替换为现有订阅的名称。例如:
postgres=> select pglogical.drop_subscription(subscription_name := 'test_sub'); -[ RECORD 1 ]-----+-- drop_subscription | 1
- 在目标(副本)上重新创建 pglogical 订阅,方法是向 Cloud SQL 主实例提供连接详细信息,如下所示:
SELECT pglogical.create_subscription( subscription_name := 'test_sub', provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword' );
例如:
postgres=> SELECT pglogical.create_subscription( postgres(> subscription_name := 'test_sub', postgres(> provider_dsn := 'host=10.58.64.90 port=5432 dbname=postgres user=postgres password=postgres' postgres(> ); -[ RECORD 1 ]-------+----------- create_subscription | 2769129391
- 使用以下命令检查订阅的状态:
SELECT * FROM pglogical.show_subscription_status('test_sub');
- 通过执行写入事务并验证更改在目标位置是否可见来测试复制。
- 使用以下命令删除目标副本上的
升级读取副本。
如果您停止了读取副本的复制,请逐个升级副本。您可以使用用于升级主实例的任何方法。 当您升级副本时,Cloud SQL 会重新创建它以保留 IP 地址,使用主实例中的最新数据刷新副本,然后重启副本。
如果您在升级主实例之前删除了读取副本,则可以创建新的读取副本,该副本会自动在升级后的数据库版本上预配。
刷新数据库统计信息。
对主实例运行
ANALYZE
以在升级后更新系统统计信息。准确的统计信息可确保 PostgreSQL 查询规划器以最优方式处理查询。缺少统计信息可能会导致查询计划错误,进而可能会降低性能并占用过多内存。执行验收测试。
您应该运行测试以确保升级的系统按预期运行。
排查主要版本升级问题
如果您尝试执行无效的升级命令(例如,如果实例包含新版本的无效数据库标志),则 Cloud SQL 会返回错误消息。
如果升级请求失败,请检查升级请求的语法。如果请求的结构有效,请尝试查看以下建议。
查看升级前检查失败
升级前检查失败是 Cloud SQL 在升级前验证或验证过程中检测到的问题或错误。这些故障在实际升级过程开始之前发生,旨在找出可能会影响升级成功的潜在问题或不兼容问题。
系统针对以下类别显示升级前检查失败:
- 不兼容的扩展程序:检测与实例的目标版本不兼容的 PostgreSQL 扩展程序。
- 不受支持的依赖项:确定不再受支持或需要更新的依赖项。
- 数据格式不兼容:验证由各种因素引起的数据不一致,包括特定于版本的数据结构的差异、编码和排序规则的更改、数据类型的修改以及对系统目录的调整。
下表列出了升级前检查失败及其错误消息:
升级前检查失败 | 错误消息 |
---|---|
Cloud SQL 检测到未知数据类型。 | Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name) |
升级到 PostgreSQL 12 或更高版本时,Cloud SQL 会检测 'sql_identifier' 数据类型。 |
Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name) |
Cloud SQL 会检测 reg* 数据类型。 |
Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name) |
Cloud SQL 检测到 postgres 数据库的 LC_COLLATE 值是 en_US.UTF8 以外的字符集。 |
Please change the 'LC_COLLATE' value of the postgres database to 'en_US.UTF8' before attempting an upgrade |
Cloud SQL 会检测具有对象标识符 (OID) 的表。 | Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name) |
Cloud SQL 可检测复合数据类型。 | Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name) |
Cloud SQL 可检测用户定义的后缀运算符。 | Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, operation id: op_id, operation namespace: op_namespace, operation name: op_name, type namespace: type_namespace, type name: type_name) |
Cloud SQL 检测到不兼容的多态函数。 | Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: db_name, object kind: obj_kind, object name: obj_name) |
Cloud SQL 可检测用户定义的编码转换。 | Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: db_name, namespace name: namespace_name, encoding conversions name: encod_name) |
查看升级日志
如果有效升级请求出现任何问题,Cloud SQL 会将错误日志发布到 projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log
。 每个日志条目都包含标签,用于标识实例标识符,以帮助您识别升级错误的实例。 请查找此类升级错误并加以解决。
如需查看错误日志,请按照以下步骤操作:
-
在 Google Cloud 控制台中,转到 Cloud SQL 实例页面。
- 如需打开实例的概览页面,请点击实例名称。
在实例概览页面的操作和日志窗格中,点击查看 PostgreSQL 错误日志 (View PostgreSQL error logs) 链接。
日志浏览器页面随即会打开。
按以下方式查看日志:
- 如需列出项目中的所有错误日志,请在日志名称日志过滤条件中选择日志名称。
如需详细了解查询过滤条件,请参阅高级查询。
- 如需过滤单个实例的升级错误日志,请在搜索所有字段框中输入以下查询,将
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
标志值。更改此标志的值时,实例将重启。
检查 PostgreSQL 实例的版本
如果您使用的是 Cloud SQL for PostgreSQL 实例的 9.6、10 或 11 版,并且已为该实例启用了 PostGIS 扩展程序,则 PostGIS 升级可能会由于权限问题而失败。如需解决此问题,请使用自助维护发布最新的系统管理器 (SSM) 映像。这可为您提供升级 PostGIS 的权限。
检查 PostgreSQL 实例的自定义标志
如果要升级到 PostgreSQL 实例 14 版或更高版本,请检查为该实例配置的任何自定义数据库标志的名称。这是因为 PostgreSQL 为允许的自定义参数名称施加了额外限制。
自定义数据库标志的第一个字符必须是字母(A-Z 或 a-z)。所有后续字符可以是字母数字字符、下划线 (_) 特殊字符或美元符号 ($) 特殊字符。
移除扩展程序
如果您要将 Cloud SQL 实例从版本 10 升级到版本 14,则可能会看到以下错误消息:pg_restore: error: could not execute
query: ERROR: role "16447" does not exist
。
如需解决此问题,请按以下步骤操作:
- 移除
pg_stat_statements
和pgstattuple
扩展程序。 - 执行升级。
- 重新安装扩展程序。
恢复到先前的主要版本
如果升级后的数据库系统未按预期运行,您可能需要将实例恢复到先前版本。您可以通过将升级前备份恢复到 Cloud SQL 恢复实例来执行此操作,该实例是运行升级前版本的新实例。
如需恢复到先前的版本,请执行以下步骤:
确定升级前备份。
请参阅自动升级备份。
创建恢复实例。
使用升级前备份时 Cloud SQL 运行的主要版本创建新的 Cloud SQL 实例。设置与原始实例相同的标志和实例设置。
恢复升级前备份。
将升级前备份恢复到恢复实例。此命令可能需要几分钟才能完成。
添加读取副本。
如果您使用的是读取副本,请单独添加。
连接您的应用。
恢复数据库系统后,使用有关恢复实例及其读取副本的详细信息来更新应用。您可以继续在数据库的升级前版本上处理流量。
限制
本部分列出了主要版本就地升级的限制。
- 您不能对外部副本执行主要版本就地升级。
常见问题解答
升级数据库主要版本时,可能会出现以下问题。
- 不可用。在 Cloud SQL 执行升级期间,您的实例在一段时间内不可用。
- 升级需要多长时间?
升级单个实例通常不到 10 分钟。如果您的实例配置使用少量 vCPU 或内存,则升级可能需要更多时间。
如果您的实例托管过多数据库或表,或者您的数据库非常大,则升级可能需要几个小时,甚至超时,因为升级时间与数据库中的对象数量相对应。如果您有多个实例需要升级,那么总升级时间会按比例增加。
- 我可以监控升级过程的每个步骤吗?
- Cloud SQL 支持您监控升级操作是否仍在进行中,但您无法跟踪每次升级中的各个步骤。
- 升级后是否可以取消?
- 不可以,升级一旦开始就无法取消。如果升级失败,Cloud SQL 会自动恢复您在先前版本上的实例。
- 升级期间,我的设置会发生什么情况?
执行主要版本就地升级时,Cloud SQL 会保留您的数据库设置,包括实例名称、IP 地址、明确配置的标志值和用户数据。但是,系统变量的默认值可能会发生变化。例如,PostgreSQL 13 及更低版本中
password_encryption
标志的默认值为md5
。升级到 PostgreSQL 14 后,此标志的默认值会更改为scram-sha-256
。如需了解详情,请参阅配置数据库标志。如果目标版本中不再支持特定标志或值,则 Cloud SQL 会在升级期间自动移除该标志。