Get the major upgrade
Each PostgreSQL major of the pinned release that is newer than the major of the service (ADR 2026-10-22 D9), with its minors and why Check cannot take a minor, the default minor (the newest minor with a build of the current TimescaleDB version and of the current version of each extension), the version of each extension after the upgrade (P1, D5, P9), and its blockers. available is the next major. The report of the last Check, the state of the last Upgrade (with the fingerprint that an air-gapped console needs a grant for), the removal of the files of the earlier major (P4), and the rollback to the earlier major after a Copy upgrade (D8) with its last run.
/api/v1/database-services/{id}/major-upgradetse_sessionAPI key · cookierequiredidstringrequiredOK
availableMajorUpgradePlanrequiredThe default target of a major upgrade from the pinned release (P1): the next major, with its blockers
Show propertiesHide properties
blockersstring[]requiredextensionsMajorUpgradeExtension[]requiredShow propertiesHide properties
MajorUpgradeExtensionfollows_majorbooleanThe version of the extension follows the PostgreSQL major. The upgrade drops it before pg_upgrade and creates it at the new version after the start.
fromstringrequiredkeptbooleanA kept extension: it exists in a database, and the service does not ask for it
namestringrequiredtostringrequiredfromstringrequiredmajorstringrequiredminorstringrequiredminorsMajorUpgradeMinor[]requiredEach minor of the target major in the pinned release, newest first, and if Check can take it (TSE-1116). The default minor is the newest eligible minor.
Show propertiesHide properties
MajorUpgradeMinoreligiblebooleanrequiredThe minor has a build of the current TimescaleDB version and the current version of each extension of the service. Check can take it.
minorstringrequiredreasonstringWhy the minor is not eligible
missing_optionalstring[]requiredreleasestringrequiredcleanupMajorCleanupInforequiredShow propertiesHide properties
availablebooleanrequiredPOST /database-services/{id}/major-upgrade/cleanup can run now
old_majorstringMajor N, while its files stay on the servers
refusalstringWhy the cleanup cannot run now
last_checkMajorCheckReportShow propertiesHide properties
backupUpgradeBackupInforequiredThe backup state, for a Back up now action (a full backup). The backup gate has no override.
Show propertiesHide properties
can_back_upbooleanrequiredA backup can start now: backups are configured and no backup runs
configuredbooleanrequiredThe service has backups configured
last_backup_atstringThe stop time of the newest successful backup
runningbooleanrequiredA backup runs now
currentbooleanrequiredThe service still has the versions and the pin that the check read. Upgrade runs the plan only then.
modesMajorModeReport[]requiredEach mode of pg_upgrade with its window estimate, and whether its rows passed (ADR 2026-10-22 D7)
Show propertiesHide properties
MajorModeReportdisk_bytesinteger<int64>requiredWhat pg_upgrade writes on the data file system of the primary in this mode, in bytes: the new catalog (Link, Swap) or a copy of the data (Copy). 0 when unknown.
disk_okbooleanrequiredfree_bytes covers disk_bytes plus reserve_bytes: the disk row of this mode passed
free_bytesinteger<int64>requiredThe free space on that file system at the time of the Check, in bytes
modestringrequiredlinkcopyswappassedbooleanrequiredNo row of this mode failed. Upgrade refuses a mode that did not pass.
rebuild_secondsinteger<int64>requiredThe estimate of the rebuild of one replica after the window in seconds (Copy and Swap on a service with replicas), else 0
reserve_bytesinteger<int64>requiredThe emergency reserve that must stay free on that file system, in bytes
window_secondsinteger<int64>requiredThe estimate of the maintenance window in this mode in seconds, 0 when unknown
passedbooleanrequiredThe check completed with no failed row
planMajorUpgradePlanrequiredThe target of this Check: the major and the minor of N+1 (any newer major of the pinned release), each extension with its version after the upgrade, and the blockers
Show propertiesHide properties
blockersstring[]requiredextensionsMajorUpgradeExtension[]requiredfromstringrequiredmajorstringrequiredminorstringrequiredminorsMajorUpgradeMinor[]requiredEach minor of the target major in the pinned release, newest first, and if Check can take it (TSE-1116). The default minor is the newest eligible minor.
missing_optionalstring[]requiredreleasestringrequiredrowsMajorCheckRow[]requiredShow propertiesHide properties
MajorCheckRowcheckstringrequiredpackagestargetbackupwriteslivesyncpatronidcsgranttsdbeinstallrsyncpg_upgradeextensionsagetablespacepgauditparametersdiskearlier_majorpgbouncerwindowdatabasestringThe database of a row of one database
detailstringrequiredmodestringThe mode of pg_upgrade of a row of one mode. A failed row of a mode refuses only that mode.
linkcopyswapparameterstringThe PostgreSQL parameter of a row of one parameter. The user changes it on the Configuration tab of the service.
serverstringThe server of a row of one server
statusstringrequiredpasswarnfailstarted_atstringrequiredstatusstringrequiredThe status of the check workflow
runningcompletedfailedtimeoutinterruptedwindow_secondsinteger<int64>requiredThe estimate of the maintenance window in Link mode in seconds, 0 when unknown
workflow_idstringrequiredlast_rollbackMajorRollbackReportThe last rollback to major N after the last Upgrade
Show propertiesHide properties
fromstringrequiredMajor N, the major that the service goes back to
grant_waitMajorGrantWaitInfoSet while the rollback waits for a pasted licence grant for the old cluster (an air-gapped console). POST /database-services/{id}/major-upgrade/grant takes it.
Show propertiesHide properties
account_idstringfingerprintstringrequiredThe fingerprint of the new cluster: <system identifier>:<database oid>
license_idstringrequiredno_returnbooleanrequiredThe rollback passed its point of no return: the service runs major N
rebuildstring[]requiredThe replicas that the console rebuilds with the Patroni-only rebuild
stanza_pendingbooleanThe rollback brought back major N with its clients, and only its stanza step did not complete. The run is not offered again; stanza_pending of the status tells whether the stanza step is still to run.
started_atstringrequiredstatusstringrequiredrunningcompletedfailedtimeoutinterruptedtostringrequiredMajor N+1
workflow_idstringrequiredlast_upgradeMajorUpgradeReportShow propertiesHide properties
forward_onlybooleanrequiredThe window in Swap mode stopped after pg_upgrade started to move the files, before the point of no return. PostgreSQL N cannot start on the leader again, and the service is down. POST /database-services/{id}/major-upgrade continues the window forward; else restore the backup into a new service on major N.
fromstringrequiredMajor N
grant_waitMajorGrantWaitInfoSet while Upgrade waits for a pasted licence grant for the new cluster (an air-gapped console). POST /database-services/{id}/major-upgrade/grant takes it.
Show propertiesHide properties
account_idstringfingerprintstringrequiredThe fingerprint of the new cluster: <system identifier>:<database oid>
license_idstringrequiredmodestringrequiredThe mode of pg_upgrade (ADR 2026-10-22 D7)
linkcopyswapno_returnbooleanrequiredThe window passed the point of no return: the service runs major N+1
rebuildstring[]requiredThe replicas that the console rebuilds with the Patroni-only rebuild
revertedbooleanrequiredA rollback after the start (tier 2, ADR 2026-10-22 D8) passed its point of no return: the service went back to major N
rollback_onlybooleanThe run is the tier-1 rollback after a restart of the console: it takes the service back to major N and does not upgrade. Also set on a run whose window started and whose tier-1 rollback did not end. When it does not end, rollback.before_start offers the tier-1 rollback again.
rolled_backbooleanrequiredThe window failed before the point of no return, and the service went back to major N
started_atstringrequiredstatusstringrequiredrunningcompletedfailedtimeoutinterruptedtostringrequiredMajor N+1
workflow_idstringrequiredreconcilingbooleanThe console restarted during the last major upgrade or rollback, and it still reads the servers to find how far the run went. The offer and the state of the run can change when it ends.
refusalstringWhy the console cannot offer a major upgrade now, for example the pinned server packages are not loaded
rollbackMajorRollbackInfoThe rollback to major N after the start of N+1 (ADR 2026-10-22 D8), while the console offers it
Show propertiesHide properties
availablebooleanrequiredPOST /database-services/{id}/major-upgrade/rollback can run now
before_startbooleanA restart of the console stopped the last Upgrade before the point of no return. The rollback is tier 1: major N starts again from its own data directory, and no write is lost.
continuebooleanThe last rollback passed its point of no return and did not complete: the service runs major N. A new run continues it.
old_majorstringMajor N, while the console can offer the rollback to it: the last Upgrade passed the point of no return, and no Cleanup ran after it
refusalstringWhy the rollback cannot run now
stanza_pendingbooleanA rollback brought back major N, but the backup stanza is not set back to N: WAL archiving and backups fail. POST /database-services/{id}/major-upgrade/stanza runs the stanza step again.
targetsMajorUpgradePlan[]requiredEach target of a major upgrade: each major of the pinned release newer than the major of the service, oldest first, with its blockers (ADR 2026-10-22 D9). Check takes one of them.
Show propertiesHide properties
MajorUpgradePlanblockersstring[]requiredextensionsMajorUpgradeExtension[]requiredShow propertiesHide properties
MajorUpgradeExtensionfollows_majorbooleanThe version of the extension follows the PostgreSQL major. The upgrade drops it before pg_upgrade and creates it at the new version after the start.
fromstringrequiredkeptbooleanA kept extension: it exists in a database, and the service does not ask for it
namestringrequiredtostringrequiredfromstringrequiredmajorstringrequiredminorstringrequiredminorsMajorUpgradeMinor[]requiredEach minor of the target major in the pinned release, newest first, and if Check can take it (TSE-1116). The default minor is the newest eligible minor.
Show propertiesHide properties
MajorUpgradeMinoreligiblebooleanrequiredThe minor has a build of the current TimescaleDB version and the current version of each extension of the service. Check can take it.
minorstringrequiredreasonstringWhy the minor is not eligible
missing_optionalstring[]requiredreleasestringrequiredError
codestringStable code of the refusal, when the route has codes
detailsstring[]Additional detail, e.g. per-field validation failures
errorstringrequiredHuman-readable error message