Skip to content
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview

Run a major upgrade

Runs the plan of the last passed Check of the major upgrade (ADR 2026-10-22 decision items 3 to 6) in the mode of the request (D7): link (the default), copy or swap. Before the window, with no downtime: the new cluster on the leader, and the licence grant of the new cluster (the console retires the database record of the old cluster, registers the new one and mints the grant; an air-gapped console waits for the grant in a bundle on POST /license/bundle). The window: pgBouncer pauses, PostgreSQL stops, pg_upgrade –link, –copy or –swap, in Link mode the copy to the replicas, stanza-upgrade, the new cluster starts and the grant opens writes. In Copy and Swap mode the console rebuilds every replica after the start. A failure before the point of no return goes back to the old major, except in Swap mode after pg_upgrade started to move the files: then the console continues the window forward, and a later call continues it again (last_upgrade.forward_only). After the start, a full backup runs. The workflow is upgrade_major. 422 for swap with a target before PostgreSQL 18. 409 when the last Check did not pass, is older than one hour or no longer matches the service or the loaded server packages, when the mode did not pass the last Check, or when the backup gate refuses.

POST/api/v1/database-services/{id}/major-upgrade
Authorization
tse_sessionAPI key · cookierequired
Path parameters
idstringrequired
Request body
application/json
modestring

The mode of pg_upgrade (ADR 2026-10-22 D7). link (the default): hard links, the fastest; PostgreSQL N can start again until the new cluster starts. copy: pg_upgrade copies the data; the leader needs free disk equal to the data, and the data directory of N stays unmodified until the cleanup. swap (target 18 or later): pg_upgrade moves the data files; after the transfer starts, PostgreSQL N cannot start on the leader again. In Copy and Swap mode the console rebuilds every replica after the start.

Allowed:linkcopyswap
Responses
202

Accepted

workflow_idstringrequired
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 POST 'https://console.example.com/api/v1/database-services/string/major-upgrade' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "link"
}'
Response
{
  "workflow_id": "string"
}