Troubleshoot an in-place major version upgrade

This document describes how to troubleshoot issues you might encounter while upgrading your AlloyDB for PostgreSQL database to an in-place major version. For more information, see Upgrade a database in-place major version. To learn about in-place major version upgrade errors, see Database in-place major version upgrade errors.

To analyze upgrade failures, identify the failed upgrade stage from the response and use the information in this document to identify possible resolutions.

AlloyDB validates your request synchronously and returns an error message if any of the following are true:

  • Request is invalid. For example, if the provided target major version isn't supported or is less than or equal to the current major version.
  • The cluster resources are in a state in which the major version upgrade can't be triggered. For example, if the cluster or any of the associated instances aren't in a READY state.

If the request is valid, the upgrade might fail due to the following reasons:

  • Pre-upgrade checks performed at various stages can fail, which indicates that violations are detected. You must address these violations before you restart the upgrade.
  • Internal errors mean that you need to retry the upgrade. If retries fail, contact Google Cloud Support.

AlloyDB pre-upgrade check failures

Pre-upgrade check failures can happen during any of the following stages:

  • AlloyDB pre-upgrade checks (ALLOYDB_PRECHECK)
  • pg_upgrade checks (PG_UPGRADE_CHECK)
  • Primary cluster upgrades (PRIMARY_INSTANCE_UPGRADE)

Pre-upgrade check failures are issues that AlloyDB detects during the pre-upgrade validation phase, which can cause the in-place major version upgrade to fail. For example, AlloyDB checks for extension incompatibilities between the current and target major version.

Error messages are populated in the logs_url in the upgrade operation response. You can view these logs by navigating to Logs Explorer in the Google Cloud console. For more information, see View upgrade logs.

To view the failures and the corresponding error messages that you might see in the logs, see Database in-place major version upgrade errors.

The following is an example of the summary that's generated in the logs by AlloyDB pre-upgrade checks:

Total number of databases checked for custom checks: 
Total number of databases containing pg_largeobject: 
Total number of databases containing extensions compatibility violation:

pg_upgrade check failures

PG_UPGRADE_CHECK checks for violations using the standard pg_upgrade utility. This upgrade check includes data inconsistencies that arise from various factors, including differences in version-specific data structures, alterations in encoding and collation, modifications to data types, and adjustments to the system catalog.

Multiple files –like tables_with_oids.txt and tables_using_reg.txt, which are generated during pg_upgrade– are exported to postgres_upgrade. You can filter these files using the label labels.FILE_NAME.

Filenames that might contain errors to resolve include the following:

Filename Description

tables_with_oids.txt

This file contains tables that are listed with object identifiers (OIDs). Delete the tables or modify them so that they don't use OIDs.

tables_using_composite.txt

This file contains tables that are listed using system-defined composite types. Delete the tables or modify them so that they don't use these composite types.

tables_using_unknown.txt

This file contains tables that are listed using the UNKNOWN data type. Delete the tables or modify them so that they don't use this data type.

tables_using_sql_identifier.txt

This file contains tables that are listed using the SQL_IDENTIFIER data type. Delete the tables or modify them so that they don't use this data type.

tables_using_reg.txt

This file contains tables that are listed using the REG* data type –for example, REGCOLLATION or REGNAMESPACE. Delete the tables or modify them so that they don't use this data type.

postfix_ops.txt

This file contains tables that are listed using postfix (right-unary) operators. Delete the tables or modify them so that they don't use these operators.

pg_upgrade failures

The structure of PG_UPGRADE logs is similar to the structure of PG_UPGRADE_CHECK logs.

The following is an example of a log with the label labels.FILE_NAME=pg_upgrade_dump*.log:

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

What's next