---
search:
  tags:
    - database-services
    - POST
seo:
  description: >-
    Runs the plan of the last passed Check of the… Reference for the POST
    /api/v1/database-services/{id}/major-upgrade endpoint in the TimescaleDB
    Enterprise API.
  noindex: true
sidebar:
  label: Run a major upgrade
  badge: POST
title: Run a major upgrade
type: openapi-operation
---
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`

**Request body** (`application/json`)

- `mode` (string) — 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.

Request body example:

```json
{
  "mode": "link"
}
```

**Responses**

- `202` — Accepted
- `default` — Error

Response example, 202:

```json
{
  "workflow_id": "string"
}
```
