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

Get the available upgrade

The items that the loaded server packages can move: the PostgreSQL minor, each extension, Patroni and pgBouncer. The default selection has each item at the newest version of the pinned release, with the items that they need (ADR 2026-10-21 decisions 2 and 30). The options have every target, also from newer releases, each with what Check adds with it (TSE-1066). And the console components that the loaded server components can move: pgBackRest of the backup group, tsdbe, etcd, confd, the exporters, pg_auto_reindexer and Tailscale (decisions 29 to 34). And the report of the last Check.

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

OK

availableUpgradePlanrequired

The default selection: every item that the pinned server packages have at a newer version, at the newest version of the pinned release, with the items that it needs. A newer release is never a default (TSE-1066).

Show properties
blockersstring[]required
itemsUpgradeItem[]required
Show properties
Array of UpgradeItem
addedboolean

Check added the item, because a picked item needs it

effectstring

What the item does to the service and its clients

fromstringrequired
keptboolean

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

labelstring

The name of the item for the user

namestringrequired
notestring

More about the item: the other services of a shared item, or why it is required

reasonstring

Why Check added the item

releasestring

The release of the components pack or of the server packages of the target

requiredboolean

A server runs a version below the compatibility floor of the console (console/catalog/components.yml). Check adds the item; Reason tells why.

serversstring[]

The servers that the item moves

servicesstring[]

The other services that use the servers of a shared item (a backup server, a standalone DCS cluster)

sourcestring

Where the target comes from, for example components pack v0.12.0

stepstring

How a component item moves. rolling_pass: in the down window of each server of the rolling pass. member_by_member: one server at a time, with a health wait, no PostgreSQL restart. in_place: on each server, no PostgreSQL restart. pgbackrest_group: every server of the backup group in one step, no PostgreSQL restart. tailscale: one server at a time, a short mesh interruption.

Allowed:rolling_passmember_by_memberin_placepgbackrest_grouptailscale
tostringrequired
missing_optionalstring[]required
releasestringrequired
last_checkUpgradeCheckReport
Show properties
backupUpgradeBackupInforequired

The backup state, for a Back up now action (the backup operation). The upgrade never takes a backup.

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

backup_risksstring[]required

The backup warnings of the check. Upgrade needs accept_backup_risk when there is one.

currentbooleanrequired

The service still has the versions, the pin and the servers that the check read, and no restore started after the check. Upgrade runs the plan only then.

passedbooleanrequired

The check completed with no failed row

planUpgradePlanrequired

The resolved selection: the picked items, the items that Check added with their reason, and the blockers

Show properties
blockersstring[]required
itemsUpgradeItem[]required
missing_optionalstring[]required
releasestringrequired
requestUpgradeRequest[]required
Show properties
Array of UpgradeRequest
namestringrequired

postgresql, patroni, pgbouncer, haproxy, keepalived, the catalog name of an extension of the service (timescaledb, pgvector and so on), or a console component item: pgbackrest, tsdbe, etcd, confd, dcs_etcd, node_exporter, postgres_exporter, pgbouncer_exporter, sql_exporter, pg_auto_reindexer, tailscale, backup_server_tailscale, dcs_tailscale

targetstring

The version to move to. Empty: the newest version in the loaded server packages or server components. A component at the version that its servers have already is copied and restarted again.

rowsUpgradeCheckRow[]required
Show properties
Array of UpgradeCheckRow
checkstringrequired
Allowed:packagesitemsbackuppgbackrestwriteslivesyncpatronidcstransactionsdatallowconnupdate_pathsoptional_extensionsinstallrollback_versionsdiskpgbackrest_groupdcs_cluster
databasestring

The database of a row of one database

detailstringrequired
serverstring

The server of a row of one server

statusstringrequired
Allowed:passwarnfail
started_atstringrequired
statusstringrequired

The status of the check workflow

Allowed:runningcompletedfailedtimeoutinterrupted
upgradedbooleanrequired

An Upgrade with the plan of this check completed. Upgrade runs a check once: run Check again for the next upgrade.

workflow_idstringrequired
last_upgradeUpgradeRunReport
Show properties
actorstring

Who started the upgrade

finished_atstring
itemsUpgradeItem[]required

The items of the plan, each from its version before the upgrade to its target

Show properties
Array of UpgradeItem
addedboolean

Check added the item, because a picked item needs it

effectstring

What the item does to the service and its clients

fromstringrequired
keptboolean

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

labelstring

The name of the item for the user

namestringrequired
notestring

More about the item: the other services of a shared item, or why it is required

reasonstring

Why Check added the item

releasestring

The release of the components pack or of the server packages of the target

requiredboolean

A server runs a version below the compatibility floor of the console (console/catalog/components.yml). Check adds the item; Reason tells why.

serversstring[]

The servers that the item moves

servicesstring[]

The other services that use the servers of a shared item (a backup server, a standalone DCS cluster)

sourcestring

Where the target comes from, for example components pack v0.12.0

stepstring

How a component item moves. rolling_pass: in the down window of each server of the rolling pass. member_by_member: one server at a time, with a health wait, no PostgreSQL restart. in_place: on each server, no PostgreSQL restart. pgbackrest_group: every server of the backup group in one step, no PostgreSQL restart. tailscale: one server at a time, a short mesh interruption.

Allowed:rolling_passmember_by_memberin_placepgbackrest_grouptailscale
tostringrequired
releasestringrequired

The release of the plan

started_atstringrequired
statusstringrequired

The status of the upgrade workflow

Allowed:runningcompletedfailedtimeoutinterrupted
workflow_idstringrequired
optionsUpgradeOption[]required

Each package item with each target that the loaded server packages have for it, newest first, also from newer releases. Each target has its release and the items that Check adds with it (TSE-1066).

Show properties
Array of UpgradeOption
fromstringrequired

The installed version. For Patroni, pgBouncer, HAProxy and keepalived, the version of the pinned pack.

keptboolean

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

namestringrequired
targetsUpgradeTarget[]required

Each version above the installed version that the pinned pack or a newer loaded release has, newest first

Show properties
Array of UpgradeTarget
moves_pinboolean

Only a newer release has the target: the upgrade moves the pin

needsUpgradeNeed[]required

The items that Check adds when the request picks this item alone at this version

Show properties
Array of UpgradeNeed
namestringrequired

The item, for example postgresql

reasonstringrequired

Why the target needs the item

tostringrequired

The version of the item that the target needs

releasestringrequired

The release of the target: the pin after an upgrade of this item alone

versionstringrequired
recheckstring

Why Check can find an item that available does not have: the last upgrade did not complete, or a restore ran after the last check. Check then finds the catalog step of an extension whose catalog is behind its package (ADR 2026-10-21 decision 21).

refusalstring

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

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/upgrade' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json'
Response
{
  "available": {
    "blockers": [
      "string"
    ],
    "items": [
      {
        "added": true,
        "effect": "string",
        "from": "string",
        "kept": true,
        "label": "string",
        "name": "string",
        "note": "string",
        "reason": "string",
        "release": "string",
        "required": true,
        "servers": [
          "string"
        ],
        "services": [
          "string"
        ],
        "source": "string",
        "step": "rolling_pass",
        "to": "string"
      }
    ],
    "missing_optional": [
      "string"
    ],
    "release": "string"
  },
  "last_check": {
    "backup": {
      "can_back_up": true,
      "configured": true,
      "last_backup_at": "string",
      "running": true
    },
    "backup_risks": [
      "string"
    ],
    "current": true,
    "passed": true,
    "plan": {
      "blockers": [
        "string"
      ],
      "items": [
        {
          "added": true,
          "effect": "string",
          "from": "string",
          "kept": true,
          "label": "string",
          "name": "string",
          "note": "string",
          "reason": "string",
          "release": "string",
          "required": true,
          "servers": [
            "string"
          ],
          "services": [
            "string"
          ],
          "source": "string",
          "step": "rolling_pass",
          "to": "string"
        }
      ],
      "missing_optional": [
        "string"
      ],
      "release": "string"
    },
    "request": [
      {
        "name": "string",
        "target": "string"
      }
    ],
    "rows": [
      {
        "check": "packages",
        "database": "string",
        "detail": "string",
        "server": "string",
        "status": "pass"
      }
    ],
    "started_at": "string",
    "status": "running",
    "upgraded": true,
    "workflow_id": "string"
  },
  "last_upgrade": {
    "actor": "string",
    "finished_at": "string",
    "items": [
      {
        "added": true,
        "effect": "string",
        "from": "string",
        "kept": true,
        "label": "string",
        "name": "string",
        "note": "string",
        "reason": "string",
        "release": "string",
        "required": true,
        "servers": [
          "string"
        ],
        "services": [
          "string"
        ],
        "source": "string",
        "step": "rolling_pass",
        "to": "string"
      }
    ],
    "release": "string",
    "started_at": "string",
    "status": "running",
    "workflow_id": "string"
  },
  "options": [
    {
      "from": "string",
      "kept": true,
      "name": "string",
      "targets": [
        {
          "moves_pin": true,
          "needs": [
            {
              "name": "string",
              "reason": "string",
              "to": "string"
            }
          ],
          "release": "string",
          "version": "string"
        }
      ]
    }
  ],
  "recheck": "string",
  "refusal": "string"
}