Skip to main content
Some maintenance, such as security fixes and Postgres and image updates, requires restarting Postgres. Restarts are brief, and most applications get through them with minimal impact, especially with a dedicated PgBouncer and replicas. Still, you should decide when they happen. Every production branch has a weekly two-hour maintenance window. Most windows only run routine maintenance, which doesn’t restart Postgres, and we email your database administrators at least 7 days before a restart.

​
Types of maintenance

In rare cases, such as a critical security vulnerability, we may need to restart outside your maintenance window or with less than 7 days’ notice.

​
Change your maintenance window

Every production branch gets a maintenance window in UTC when it’s created, and the dashboard also shows it in your local time zone.
Settings Maintenance page showing each production branch's weekly maintenance window, with Change schedule and View historySettings Maintenance page showing each production branch's weekly maintenance window, with Change schedule and View history
1
From the PlanetScale dashboard, select your database.
2
Open Settings, then select Maintenance.
3
Find the production branch and select Change schedule.
4
Choose the day of the week and the hour in UTC. The window lasts two hours.
5
Select Save.
Only database administrators can change a maintenance window. Select View history to see past windows. If restart-required maintenance is already scheduled, changing your window moves it to the new window. You can’t choose a window that doesn’t open before the maintenance’s deadline.

​
Restart-required maintenance

We email your database administrators and send webhooks at each of the below steps. Each notice includes information about what’s changing, why, what to expect, and the deadline. Maintenance starts within 10 minutes after your window’s start time. Most maintenance finishes well within the window, but in rare cases it can run past the end.

​
Reschedule maintenance

Each email links to the maintenance event in your dashboard. You can also find scheduled events under Settings > Maintenance.
Upcoming maintenance card for a Postgres image update, showing what's changing, the scheduled time, the must-run-by deadline, and the Reschedule buttonUpcoming maintenance card for a Postgres image update, showing what's changing, the scheduled time, the must-run-by deadline, and the Reschedule button
To move an event, select Reschedule and choose any upcoming window before the deadline, earlier or later than the one scheduled. You can reschedule each event up to 3 times. Only database administrators can reschedule maintenance.
Reschedule maintenance dialog showing the current scheduled time, the must-run-by deadline, and a list of upcoming windows to choose fromReschedule maintenance dialog showing the current scheduled time, the must-run-by deadline, and a list of upcoming windows to choose from

​
Apply the update yourself

If you don’t want to wait for your window, apply the update from the Clusters page. When your window opens there’s nothing left to change, so the maintenance completes without a restart.

​
What happens during the restart

Each Postgres instance restarts once, replicas first. If your branch has replicas, we switch the primary over to an updated replica before restarting it, and writes pause briefly while the switchover completes. If your branch has no replicas, Postgres is unavailable while it restarts, usually for under a minute.

​
Reduce the impact of a restart

The impact of a Postgres restart to your clients depends on how they are connected:
  • A dedicated primary PgBouncer. Client connections stay open through planned switchovers, and queries wait briefly instead of failing. See dedicated primary PgBouncers.
  • Reconnect and retry. A restart closes connections made directly to Postgres or through the local PgBouncer. Make sure your application reconnects and retries.
The connection resilience guide covers each of these in detail, and operations philosophy explains how image updates work.

​
Webhooks

Subscribe to these webhook events to get the same notices programmatically:
  • maintenance.scheduled
  • maintenance.started
  • maintenance.completed
  • maintenance.failed
  • maintenance.canceled

​
API

​
Development branches

Development branches don’t have maintenance windows. Updates can restart them at any time.

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.