Skip to content
You're viewing documentation for v2026.11.5-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview

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.

GET/api/v1/database-services/{id}/major-upgrade
Authorization
tse_sessionAPI key · cookierequired
Path parameters
idstringrequired
Responses
200

OK

availableMajorUpgradePlanrequired

The default target of a major upgrade from the pinned release (P1): the next major, with its blockers

Show properties
blockersstring[]required
extensionsMajorUpgradeExtension[]required
Show properties
Array of MajorUpgradeExtension
follows_majorboolean

The 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.

fromstringrequired
keptboolean

A kept extension: it exists in a database, and the service does not ask for it

namestringrequired
tostringrequired
fromstringrequired
majorstringrequired
minorstringrequired
minorsMajorUpgradeMinor[]required

Each 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 properties
Array of MajorUpgradeMinor
eligiblebooleanrequired

The minor has a build of the current TimescaleDB version and the current version of each extension of the service. Check can take it.

minorstringrequired
reasonstring

Why the minor is not eligible

missing_optionalstring[]required
releasestringrequired
cleanupMajorCleanupInforequired
Show properties
availablebooleanrequired

POST /database-services/{id}/major-upgrade/cleanup can run now

old_majorstring

Major N, while its files stay on the servers

refusalstring

Why the cleanup cannot run now

last_checkMajorCheckReport
Show properties
backupUpgradeBackupInforequired

The backup state, for a Back up now action (a full backup). The backup gate has no override.

Show properties
can_back_upbooleanrequired

A backup can start now: backups are configured and no backup runs

configuredbooleanrequired

The service has backups configured

last_backup_atstring

The stop time of the newest successful backup

runningbooleanrequired

A backup runs now

currentbooleanrequired

The service still has the versions and the pin that the check read. Upgrade runs the plan only then.

modesMajorModeReport[]required

Each mode of pg_upgrade with its window estimate, and whether its rows passed (ADR 2026-10-22 D7)

Show properties
Array of MajorModeReport
disk_bytesinteger<int64>required

What 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_okbooleanrequired

free_bytes covers disk_bytes plus reserve_bytes: the disk row of this mode passed

free_bytesinteger<int64>required

The free space on that file system at the time of the Check, in bytes

modestringrequired
Allowed:linkcopyswap
passedbooleanrequired

No row of this mode failed. Upgrade refuses a mode that did not pass.

rebuild_secondsinteger<int64>required

The 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>required

The emergency reserve that must stay free on that file system, in bytes

window_secondsinteger<int64>required

The estimate of the maintenance window in this mode in seconds, 0 when unknown

passedbooleanrequired

The check completed with no failed row

planMajorUpgradePlanrequired

The 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 properties
blockersstring[]required
extensionsMajorUpgradeExtension[]required
fromstringrequired
majorstringrequired
minorstringrequired
minorsMajorUpgradeMinor[]required

Each 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[]required
releasestringrequired
rowsMajorCheckRow[]required
Show properties
Array of MajorCheckRow
checkstringrequired
Allowed:packagestargetbackupwriteslivesyncpatronidcsgranttsdbeinstallrsyncpg_upgradeextensionsagetablespacepgauditparametersdiskearlier_majorpgbouncerwindow
databasestring

The database of a row of one database

detailstringrequired
modestring

The mode of pg_upgrade of a row of one mode. A failed row of a mode refuses only that mode.

Allowed:linkcopyswap
parameterstring

The PostgreSQL parameter of a row of one parameter. The user changes it on the Configuration tab of the service.

serverstring

The server of a row of one server

statusstringrequired
Allowed:passwarnfail
started_atstringrequired
statusstringrequired

The status of the check workflow

Allowed:runningcompletedfailedtimeoutinterrupted
window_secondsinteger<int64>required

The estimate of the maintenance window in Link mode in seconds, 0 when unknown

workflow_idstringrequired
last_rollbackMajorRollbackReport

The last rollback to major N after the last Upgrade

Show properties
fromstringrequired

Major N, the major that the service goes back to

grant_waitMajorGrantWaitInfo

Set 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 properties
account_idstring
fingerprintstringrequired

The fingerprint of the new cluster: <system identifier>:<database oid>

license_idstringrequired
no_returnbooleanrequired

The rollback passed its point of no return: the service runs major N

rebuildstring[]required

The replicas that the console rebuilds with the Patroni-only rebuild

stanza_pendingboolean

The 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_atstringrequired
statusstringrequired
Allowed:runningcompletedfailedtimeoutinterrupted
tostringrequired

Major N+1

workflow_idstringrequired
last_upgradeMajorUpgradeReport
Show properties
forward_onlybooleanrequired

The 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.

fromstringrequired

Major N

grant_waitMajorGrantWaitInfo

Set 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 properties
account_idstring
fingerprintstringrequired

The fingerprint of the new cluster: <system identifier>:<database oid>

license_idstringrequired
modestringrequired

The mode of pg_upgrade (ADR 2026-10-22 D7)

Allowed:linkcopyswap
no_returnbooleanrequired

The window passed the point of no return: the service runs major N+1

rebuildstring[]required

The replicas that the console rebuilds with the Patroni-only rebuild

revertedbooleanrequired

A 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_onlyboolean

The 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_backbooleanrequired

The window failed before the point of no return, and the service went back to major N

started_atstringrequired
statusstringrequired
Allowed:runningcompletedfailedtimeoutinterrupted
tostringrequired

Major N+1

workflow_idstringrequired
reconcilingboolean

The 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.

refusalstring

Why the console cannot offer a major upgrade now, for example the pinned server packages are not loaded

rollbackMajorRollbackInfo

The rollback to major N after the start of N+1 (ADR 2026-10-22 D8), while the console offers it

Show properties
availablebooleanrequired

POST /database-services/{id}/major-upgrade/rollback can run now

before_startboolean

A 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.

continueboolean

The last rollback passed its point of no return and did not complete: the service runs major N. A new run continues it.

old_majorstring

Major 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

refusalstring

Why the rollback cannot run now

stanza_pendingboolean

A 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[]required

Each 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 properties
Array of MajorUpgradePlan
blockersstring[]required
extensionsMajorUpgradeExtension[]required
Show properties
Array of MajorUpgradeExtension
follows_majorboolean

The 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.

fromstringrequired
keptboolean

A kept extension: it exists in a database, and the service does not ask for it

namestringrequired
tostringrequired
fromstringrequired
majorstringrequired
minorstringrequired
minorsMajorUpgradeMinor[]required

Each 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 properties
Array of MajorUpgradeMinor
eligiblebooleanrequired

The minor has a build of the current TimescaleDB version and the current version of each extension of the service. Check can take it.

minorstringrequired
reasonstring

Why the minor is not eligible

missing_optionalstring[]required
releasestringrequired
default

Error

codestring

Stable code of the refusal, when the route has codes

detailsstring[]

Additional detail, e.g. per-field validation failures

errorstringrequired

Human-readable error message

Request
curl -X GET 'https://console.example.com/api/v1/database-services/string/major-upgrade' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json'
Response
{
  "available": {
    "blockers": [
      "string"
    ],
    "extensions": [
      {
        "follows_major": true,
        "from": "string",
        "kept": true,
        "name": "string",
        "to": "string"
      }
    ],
    "from": "string",
    "major": "string",
    "minor": "string",
    "minors": [
      {
        "eligible": true,
        "minor": "string",
        "reason": "string"
      }
    ],
    "missing_optional": [
      "string"
    ],
    "release": "string"
  },
  "cleanup": {
    "available": true,
    "old_major": "string",
    "refusal": "string"
  },
  "last_check": {
    "backup": {
      "can_back_up": true,
      "configured": true,
      "last_backup_at": "string",
      "running": true
    },
    "current": true,
    "modes": [
      {
        "disk_bytes": 0,
        "disk_ok": true,
        "free_bytes": 0,
        "mode": "link",
        "passed": true,
        "rebuild_seconds": 0,
        "reserve_bytes": 0,
        "window_seconds": 0
      }
    ],
    "passed": true,
    "plan": {
      "blockers": [
        "string"
      ],
      "extensions": [
        {
          "follows_major": true,
          "from": "string",
          "kept": true,
          "name": "string",
          "to": "string"
        }
      ],
      "from": "string",
      "major": "string",
      "minor": "string",
      "minors": [
        {
          "eligible": true,
          "minor": "string",
          "reason": "string"
        }
      ],
      "missing_optional": [
        "string"
      ],
      "release": "string"
    },
    "rows": [
      {
        "check": "packages",
        "database": "string",
        "detail": "string",
        "mode": "link",
        "parameter": "string",
        "server": "string",
        "status": "pass"
      }
    ],
    "started_at": "string",
    "status": "running",
    "window_seconds": 0,
    "workflow_id": "string"
  },
  "last_rollback": {
    "from": "string",
    "grant_wait": {
      "account_id": "string",
      "fingerprint": "string",
      "license_id": "string"
    },
    "no_return": true,
    "rebuild": [
      "string"
    ],
    "stanza_pending": true,
    "started_at": "string",
    "status": "running",
    "to": "string",
    "workflow_id": "string"
  },
  "last_upgrade": {
    "forward_only": true,
    "from": "string",
    "grant_wait": {
      "account_id": "string",
      "fingerprint": "string",
      "license_id": "string"
    },
    "mode": "link",
    "no_return": true,
    "rebuild": [
      "string"
    ],
    "reverted": true,
    "rollback_only": true,
    "rolled_back": true,
    "started_at": "string",
    "status": "running",
    "to": "string",
    "workflow_id": "string"
  },
  "reconciling": true,
  "refusal": "string",
  "rollback": {
    "available": true,
    "before_start": true,
    "continue": true,
    "old_major": "string",
    "refusal": "string"
  },
  "stanza_pending": true,
  "targets": [
    {
      "blockers": [
        "string"
      ],
      "extensions": [
        {
          "follows_major": true,
          "from": "string",
          "kept": true,
          "name": "string",
          "to": "string"
        }
      ],
      "from": "string",
      "major": "string",
      "minor": "string",
      "minors": [
        {
          "eligible": true,
          "minor": "string",
          "reason": "string"
        }
      ],
      "missing_optional": [
        "string"
      ],
      "release": "string"
    }
  ]
}