이 문서에서는 데이터 마이그레이션이나 기존 인스턴스 교체 없이 데이터베이스를 최신 버전으로 업그레이드할 수 있는 PostgreSQL용 AlloyDB 데이터베이스 인플레이스 주 버전 업그레이드를 설명합니다.
PostgreSQL 커뮤니티는 새로운 기능, 성능 개선, 보안 개선사항이 포함된 새로운 주 버전을 주기적으로 출시합니다. PostgreSQL에서 새 주 버전을 출시하면 AlloyDB에서 호환되는 버전을 지원합니다.
데이터베이스를 최신 상태로 유지하려면 상위 주 버전으로 업그레이드하여 AlloyDB 클러스터를 업그레이드하면 됩니다. 인플레이스 업그레이드 기능을 사용하거나 새 AlloyDB 클러스터로 데이터를 마이그레이션하여 클러스터를 업그레이드할 수 있습니다.
인플레이스 주 버전 업그레이드는 다음과 같은 이유로 클러스터의 주 버전을 업그레이드하는 효율적인 방법입니다.
AlloyDB는 업그레이드 후 클러스터 및 인스턴스 세부정보와 인스턴스 이름, IP 주소, 데이터베이스 플래그와 같은 데이터베이스 설정을 유지합니다.
애플리케이션 연결 문자열을 변경할 필요가 없습니다.
모든 클러스터 인스턴스 (기본 및 읽기 풀)가 동일한 작업의 일부로 업그레이드됩니다.
인플레이스 주 버전 업그레이드 워크플로
클러스터에서 업그레이드를 시작하면 AlloyDB에서 다음 작업을 실행합니다.
업그레이드에 영향을 줄 수 있는 비호환성을 찾기 위해 업그레이드 전 검사를 실행합니다.
클러스터의 내부 클론을 만드는 등 주 버전 업그레이드를 준비합니다.
기본 인스턴스를 사용할 수 없게 만듭니다. 다운타임이 시작됩니다. 읽기는 읽기 풀을 통해 계속 실행할 수 있습니다.
업그레이드 전 백업을 시작합니다.
기본 인스턴스를 업그레이드합니다.
읽기 풀 인스턴스를 사용할 수 없게 만듭니다.
기본 인스턴스를 사용할 수 있게 합니다. 다운타임이 종료됩니다.
업그레이드 후 백업을 시작합니다.
읽기 풀 인스턴스를 업그레이드합니다.
업그레이드 전 검사를 통과하면 클러스터가 동일한 프로젝트의 내부 클러스터로 클론됩니다. 클러스터를 클론하는 데 필요한 백업 및 복원에는 데이터 테라바이트당 약 10분이 걸립니다.
복제 작업 중에도 원래 클러스터를 계속 사용할 수 있습니다.
클론 작업이 완료되면 업그레이드 프로세스가 시작됩니다. 기본 인스턴스가 업그레이드될 때까지는 읽기 및 쓰기 모두에 기본 인스턴스를 사용할 수 없습니다. 예상 다운타임은 일반적으로 20분에서 1시간이며 주로 데이터베이스 스키마와 객체 수에 따라 달라집니다.
기본 인스턴스가 업그레이드되면 읽기 풀 인스턴스를 사용할 수 없게 됩니다. 모든 읽기 풀 인스턴스에서 동시에 업그레이드가 시도됩니다.
다운타임은 약 20분 동안 지속될 것으로 예상됩니다.
기본 인스턴스가 업그레이드되기 전 단계에서 메이저 버전 업그레이드가 실패하면 AlloyDB는 모든 변경사항을 자동으로 롤백합니다.
기본 인스턴스가 업그레이드된 후 클러스터 버전이 타겟 버전으로 업그레이드되며 이 시점 이후의 실패에 대해서는 롤백이 트리거되지 않습니다. 예를 들어 하나 이상의 읽기 풀 인스턴스 업그레이드가 실패해도 AlloyDB는 클러스터를 롤백하지 않습니다. 이러한 경우 Google Cloud CLI 지원팀에 문의하세요.
다음 표에는 데이터베이스 크기가 다른 클러스터의 업그레이드가 완료되는 데 걸리는 시간이 대략적으로 나와 있습니다.
기본 인스턴스 업그레이드 중 특정 시점까지 업그레이드 작업을 취소할 수 있습니다. 이 시점이 지나면 업그레이드를 취소할 수 없습니다.
Google Cloud 콘솔에서 업그레이드 취소 버튼이 회색으로 표시되면 작업을 취소할 수 없습니다. Google Cloud CLI 또는 REST API를 사용하여 업그레이드 상태에서 upgradeClusterStatus를 확인하여 업그레이드를 취소할 수 있는지 확인할 수 있습니다.
cancellable가 true이면 업그레이드를 취소할 수 있습니다.
cancellable이 false이거나 상태에 없는 경우 업그레이드를 취소할 수 없습니다.
업그레이드 전후 자동 백업
주 버전 업그레이드를 수행하면 AlloyDB에서 다음 연속 백업을 자동으로 만듭니다. 여기서 XX는 소스 주 버전이고 YY는 타겟 주 버전입니다.
업그레이드 전 백업은 업그레이드가 시작되기 직전에 생성됩니다. 이 백업은 pre-upgrade-bkp-pgXX-pgYY-<uuid> 형식을 사용하여 이름이 지정됩니다. 이 백업을 사용하여 업그레이드 전 상태로 복원할 수 있습니다. 복원은 인플레이스 작업이 아니며 새 클러스터를 만듭니다.
업그레이드 후 백업은 기본 인스턴스가 업그레이드된 후에 생성됩니다. 이 백업은 post-upgrade-bkp-pgXX-pgYY-<uuid> 형식을 사용하여 이름이 지정됩니다.
연속 백업은 증분 방식입니다. 즉, 백업은 이전 연속 백업과 비교하여 변경된 데이터만 저장합니다. 이 방법을 사용하면 백업의 크기와 비용 (리소스)이 줄어들고 백업 생성 프로세스가 빨라집니다. 자세한 내용은 데이터 백업 및 복구 개요를 참고하세요.
백업 목록을 보면 업그레이드 백업이 CONTINUOUS 유형으로 나열된 것을 알 수 있습니다. 자세한 내용은 백업 목록 보기를 참고하세요.
point-in-time recovery (PITR)를 수행하려면 버전의 백업이 있어야 합니다. 업그레이드 후 백업 또는 기본 인스턴스가 업그레이드된 후 시작된 다른 백업이 완료될 때까지는 업그레이드된 클러스터에서 복구를 사용할 수 없습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eAlloyDB for PostgreSQL offers in-place major version upgrades, allowing you to upgrade your database to a newer version without data migration or replacing the existing instance, retaining cluster settings and connection details.\u003c/p\u003e\n"],["\u003cp\u003eThe in-place upgrade process involves pre-upgrade checks, creating an internal clone of the cluster, upgrading the primary instance and read pools, and automatically creating pre- and post-upgrade backups for potential restoration.\u003c/p\u003e\n"],["\u003cp\u003eDuring the upgrade, the primary instance experiences downtime (typically 20 minutes to one hour), but read operations can continue through read pools until the read pool upgrade stage, and the overall downtime depends on the size and schema of the database.\u003c/p\u003e\n"],["\u003cp\u003eThe upgrade process can be monitored through various stages and statuses, and the upgrade can be cancelled until a specific point during the primary instance upgrade, indicated by the \u003ccode\u003ecancellable\u003c/code\u003e status in the upgrade status.\u003c/p\u003e\n"],["\u003cp\u003ePre-GA features like the in-place upgrade for AlloyDB are available "as is" with potentially limited support, and the use of personal data is subject to the Cloud Data Processing Addendum.\u003c/p\u003e\n"]]],[],null,["# Database in-place major version upgrade overview\n\nThis document describes AlloyDB for PostgreSQL database in-place major version\nupgrades, which let you upgrade a database to a higher version without\nmigrating data or replacing the existing instance.\n\nThe PostgreSQL community periodically releases [new major versions](https://www.postgresql.org/support/versioning/) that contain\nnew features, performance improvements, and security enhancements. After\nPostgreSQL releases a new major version, AlloyDB\n[adds support for the compatible version](/alloydb/docs/db-version-policies#support-table).\nTo keep your database up to date, you can upgrade your AlloyDB\ncluster by upgrading to a higher major version. You can upgrade your cluster\nby using this in-place upgrade feature or by\n[migrating your data](/alloydb/docs/cluster-upgrade) to a new\nAlloyDB cluster.\n\nFor more information, see\n[Database version policies](/alloydb/docs/db-version-policies).\n\nIn-place major version upgrades are an efficient way to upgrade your\ncluster's major version for the following reasons:\n\n- AlloyDB retains cluster and instance details and database settings like the instance name, IP address, and database flags after the upgrade.\n- You don't need to change application connection strings.\n- All the cluster instances (primary and read pool) are upgraded as part of the same operation.\n\n| **Note:** To verify the upgrade process and to check for incompatibilities, we recommend that you verify the upgrade process on a cloned cluster before you upgrade your actual cluster.\n\nIn-place major version upgrade workflow\n---------------------------------------\n\nWhen you start an upgrade on your cluster, AlloyDB performs the\nfollowing actions:\n\n1. Runs pre-upgrade checks to find incompatibilities that can impact the upgrade.\n2. Prepares for the major version upgrade, which includes creating an internal clone of the cluster.\n3. Makes the primary instance unavailable. Downtime starts. Reads can still be done through read pools.\n4. Initiates a pre-upgrade backup.\n5. Upgrades the primary instance.\n6. Makes the read pool instances unavailable.\n7. Makes the primary instance available. Downtime ends.\n8. Initiates a post-upgrade backup.\n9. Upgrades read pool instances.\n\n| **Note:** When you perform an in-place major version upgrade, version-specific default values of the database flags might change. For more information, see [Configure an instance's database flags](/alloydb/docs/instance-configure-database-flags).\n\nAfter the pre-upgrade checks pass, your cluster is cloned to an internal cluster\nin the same project. The backup and restore needed to clone the cluster takes\napproximately 10 minutes per terabyte of data.\n\nDuring the clone operation, you can continue to use your original cluster.\nAfter the clone operation is complete, the upgrade process starts. The\nprimary instance is unavailable for both reads and writes until the primary\ninstance is upgraded. Expected downtime is typically 20 minutes to one hour, and\nprimarily depends on your database schema and the number of objects.\n| **Note:** You can continue to use the read pool instances while the primary instance is being upgraded.\n\nAfter the primary instance is upgraded, read pool instances become\nunavailable. Upgrades are attempted on all read pool instances concurrently.\nDowntime is expected to last approximately 20 minutes.\n\nIf the major version upgrade fails at any step before the primary instance is\nupgraded, AlloyDB automatically rolls back all changes.\n\nAfter the primary instance is upgraded, the cluster version is\nupgraded to the target version and no rollbacks are triggered for any failure\nafter this point. For example, AlloyDB doesn't roll back the\ncluster if one or more read pool instance upgrades fail. In these situations,\ncontact [Google Cloud CLI Support](https://cloud.google.com/support).\n\nThe following table gives an approximate estimation of the time taken for the\nupgrade to complete for clusters of different database sizes:\n\nFor more information, see [Upgrade a database in-place major version](/alloydb/docs/upgrade-db-inplace-major-version).\n\n### Upgrade status\n\nYou can\n[monitor the status of an in-place database major version upgrade](/alloydb/docs/upgrade-db-inplace-major-version#monitor-upgrade) operation while it's in\nprogress.\n\nThe upgrade process includes the following stages:\n\n- `ALLOYDB_PRECHECK`\n- `PG_UPGRADE_CHECK`\n- `PREPARE_FOR_UPGRADE`\n- `PRIMARY_INSTANCE_UPGRADE`\n- `READ_POOL_INSTANCES_UPGRADE`\n- `ROLLBACK`(only in case of failure before read pool upgrades)\n- `CLEANUP`\n\nThe possible states of these stages include the following:\n\n- `NOT_STARTED`\n- `IN_PROGRESS`\n- `SUCCESS`\n- `FAILED`\n- `CANCEL_IN_PROGRESS`\n- `CANCELLED`\n\n### Upgrade cancellations\n\nYou can [cancel the upgrade operation](/alloydb/docs/upgrade-db-inplace-major-version#cancel-major-version-upgrade)\nuntil a certain point during the primary instance upgrade. Once that point is\ncrossed, you can't cancel an upgrade.\n\nIn the Google Cloud console, the operation isn't cancelable if the\n**Cancel upgrade** button is grayed out. Using the Google Cloud CLI or the\nREST API, you can\ndetermine if you can [cancel the upgrade](/alloydb/docs/upgrade-db-inplace-major-version#cancel-major-version-upgrade) by checking\n`upgradeClusterStatus` in the upgrade status:\n\n- If `cancellable` is `true`, you can cancel the upgrade.\n- If `cancellable` is `false` or is missing in the status, you can't cancel the upgrade.\n\nAutomatic pre-upgrade and post-upgrade backups\n----------------------------------------------\n\nWhen you perform a major version upgrade, AlloyDB automatically\ncreates the following continuous backups, where `XX` is the source major version\nand `YY` is the target major version.\n\n- The *pre-upgrade backup* is created immediately before the upgrade starts. This backup is named using the format `pre-upgrade-bkp-pgXX-pgYY-\u003cuuid\u003e`. You can use this backup to restore to the pre-upgrade state. Note that restore is not an in-place operation and that it creates a new cluster.\n- The *post-upgrade backup* is created after the primary instance is upgraded. This backup is named using the format `post-upgrade-bkp-pgXX-pgYY-\u003cuuid\u003e`.\n\nA *continuous backup* is incremental, which means that the backup stores only\nthe data that changed relative to the previous continuous backup. This approach\nreduces the size and cost (in resources) of the backup, and speeds up the backup creation\nprocess. For more information, see\n[Data backup and recovery overview](/alloydb/docs/backup/overview).\n\nWhen you view your list of backups, the upgrade backups are listed with type\n`CONTINUOUS`. For more information, see\n[View a list of backups](/alloydb/docs/backup/list).\n\nPerforming point-in-time recovery (PITR) requires that a backup of a version is\navailable. Recovery isn't available on the upgraded cluster until the\npost-upgrade backup, or another backup that is kicked off after the primary\ninstance is upgraded, completes.\n\nWhat's next\n-----------\n\n- [Upgrade a database in-place major version](/alloydb/docs/upgrade-db-inplace-major-version)."]]