Skip to main content
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

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.
2
See whether an update is waiting with stackshift database maintenance DATABASE (GET /api/v1/databases/{id}/maintenance).
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).
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

up_to_date is true and the events feed shows maintenance_applied.

​
Common failures

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

Standby and high availability

Add a standby on another server. If the primary fails, the standby takes over and your connection address stays the same.

Parameter groups

Tune PostgreSQL settings such as work_mem or statement_timeout for one or many Dedicated databases with a reusable parameter group.

PostgreSQL version upgrades

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

Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.