> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Maintenance window and updates

> Choose the weekly window when StackShift updates your Dedicated database, see what is waiting, and apply it now if you prefer.

> [!NOTE]
>
> **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

## Goal

Keep PostgreSQL and the system under it up to date at a time that suits your traffic.

## Prerequisites

* A Dedicated database
* Write access to change the window or apply an update

## Workflow

**Step 1**

Pick a quiet time: `stackshift database settings DATABASE --data '{"maintenance_window":{"day_of_week":0,"start_minute":180}}'`. Day 0 is Sunday and the start is minutes after midnight. Times are UTC.

**Step 2**

See whether an update is waiting with `stackshift database maintenance DATABASE` (`GET /api/v1/databases/{id}/maintenance`).

**Step 3**

Do nothing and it is applied in your window. Or apply it now with `stackshift database maintenance-apply DATABASE` (`POST /api/v1/databases/{id}/maintenance/apply`).

**Step 4**

Check the result in the events feed: `maintenance_applied`, or `maintenance_failed` if it didn’t finish.

## Your window

* The window is one slot a week, 30 minutes long. If you left it out when you created the database, we picked one for you.
* Change it any time with `stackshift database settings`. A size change that is waiting for the window moves with it.
* The window is also when scheduled changes happen: updates, size changes you set to `window`, restarts for settings that need one, and automatic fast restore points.

## What is waiting

* `up_to_date` tells you whether every server of the database is on the current image. When it is `false`, `scheduled_for` shows when the update will be applied.
* `server_version` is the PostgreSQL version running now and `latest_minor` the newest one you can get. Major versions are separate: see PostgreSQL version upgrades.
* `requested` is `true` after you ask for the update to be applied now.
* When an update becomes ready you get a `maintenance_scheduled` event.

## Timing and deferral

* An update is never applied the moment it is ready. It is scheduled in the first window that starts at least 7 days after the notice, so you have a week to prepare.
* There is no setting to skip an update. You choose when by moving the window, or you apply it earlier with `maintenance/apply`.
* If an update doesn’t finish, the database keeps running its current version, you get a `maintenance_failed` warning, and we try again in the next window.
* Updates wait while a size change or a PostgreSQL version upgrade is running.

## With and without a standby

* With a standby or read replicas: they are updated first, one at a time, while the primary keeps serving. Then the database switches over to the updated standby and the old primary is updated last. Connections drop for a few seconds at the switch, so use a driver or pool that reconnects.
* Without a standby: the database is replaced in place, so it is unavailable while it restarts. Plan for a few minutes, and choose a quiet window.
* Adding a standby makes updates much smoother. See Standby and high availability.

## Availability

Dedicated databases are rolling out. If Create doesn’t offer Dedicated, it isn’t switched on for your account yet, and the API answers `403`.

## Expected result

> [!TIP]
>
> `up_to_date` is `true` and the events feed shows `maintenance_applied`.

## Common failures

> [!WARNING]
>
> * `409` “Start the database before applying maintenance.”: start it first.
> * `409` “A PostgreSQL version upgrade is in progress…”: wait for the upgrade to finish.
> * `409` “This is available on Dedicated databases.”: Starter databases are maintained by StackShift without a window setting.
> * The update ran later than you expected: it is scheduled at least 7 days after the notice, in your window.

## Related guides

> **[Standby and high availability](https://docs.stackshift.cloud/databases/standby-and-high-availability.md)**
>
> Add a standby on another server. If the primary fails, the standby takes over and your connection address stays the same.

> **[Parameter groups](https://docs.stackshift.cloud/databases/parameter-groups.md)**
>
> Tune PostgreSQL settings such as work\_mem or statement\_timeout for one or many Dedicated databases with a reusable parameter group.

> **[PostgreSQL version upgrades](https://docs.stackshift.cloud/databases/postgresql-version-upgrades.md)**
>
> Upgrade a Dedicated database to a newer PostgreSQL major version, in place with a short outage or blue/green with a switch that takes seconds.

> **[Dedicated databases](https://docs.stackshift.cloud/databases/dedicated-databases.md)**
>
> Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.