Overview of maintenance on Cloud SQL instances

This page explains how maintenance occurs on Cloud SQL instances, and how you can control the timing of maintenance. To get started, see Finding and setting maintenance windows.

What is maintenance?

Cloud SQL instances need occasional updates to fix bugs, prevent security exploits, and perform upgrades. After applying updates, Cloud SQL restarts the instances, which can cause a disruption in service. During maintenance, HA primary instances do not fail over to standby instances.

Details about production updates are documented in the release notes.

What are maintenance windows?

Maintenance windows are blocks of time when Cloud SQL schedules this maintenance to take place.

If you want to get notification of upcoming maintenance updates, you must do both of the following:

If you do not specify a preferred window, disruptive updates can happen at any time, although they generally only occur every few months.

Time-sensitive maintenance

While most maintenance operations observe the maintenance windows you define, critical service updates, such as patches for vulnerabilities that are time sensitive, might not. These updates roll out rapidly and Cloud SQL counts them as downtime against its SLA.

How do you set preferred maintenance windows on an instance?

You schedule maintenance at a selected day of the week and time, and the order that your instances are updated. You configure these options on an instance using the Preferred window and Order of update settings.

When you configure Preferred window for an instance, Cloud SQL does not initiate updates to that instance outside of the window. Maintenance occurs every few months and usually completes within a couple of minutes. It is guaranteed not to start outside your preferred window. Maintenance is not guaranteed to complete in the preferred window. Preferred windows are defined in UTC. As a consequence, Daylight savings time changes are not applied to preferred windows. You must reconfigure your preferred window to observe local time changes.

When you configure Order of update, it sets the relative timing of instance updates that might cause downtime. Timing options are Any, Earlier, or Later. All instances receive the exact same update. The difference is that later instances receive the update a week after the earlier instances are updated. Receiving an update on a single instance earlier lets you test your application with an update, before updating the rest of your instances.

The relative timing of updates is not observed between projects or regions. If you have instances with an earlier timing setting in a different project or different location (for example, in a different region) than your instances with a later timing setting, Cloud SQL makes no attempt to update the instances with the earlier timing setting first.

If you do not set the order of update, Cloud SQL chooses the timing of updates to your instance (within its preferred window, if applicable).

The Order of update setting does not affect the software version Cloud SQL applies to your instance.

To set a preferred window for maintenance now, see Setting a preferred window for maintenance on an instance.

How does maintenance affect read replicas and failover instances?

Read replicas are taken down for maintenance updates. There is no guarantee as to when the updates will occur and updates may overlap or occur very close to the primary instance update. Failover instances are taken down for maintenance updates. They receive maintenance updates right before the primary instance. You can't set a maintenance window directly on a failover instance, because it shares the maintenance window of the primary instance.

Are there design recommendations for handling maintenance shutdowns?

We recommend that you design your applications to deal with situations when your instance is not accessible for short periods of time, such as during a maintenance shutdown. To test the behavior of your application during a maintenance shutdown, restart your instance. In general, we recommend that you use only short-lived connections and exponential back-off for retrying rejected connections.

For more guidance see How do I manage connections?

How do I get maintenance notifications?

Notifications for maintenance are not sent out by default. If you want to receive maintenance notifications, you need to set the Cloud SQL Maintenance Window option in the Cloud Console Communications page, and select ON under Email. You can only receive notifications by email. You must also select a maintenance window before you can receive notifications.

Maintenance notifications are set at the project level rather than on instances. Email notifications are sent to the email address associated with your Google account. It is not possible to configure a custom email alias (for instance, a team email alias).

To receive maintenance notifications, see opting in to maintenance notifications.

Where do I find details about upcoming maintenance?

If you sign up for a maintenance notification by email, the notification is sent to your email one week before maintenance is scheduled. If you want to set an email filter for notifications, the email title is "Upcoming maintenance for your Cloud SQL instance instancename".

There are also a few places in the Console where you can see if an instance is scheduled for a maintenance update:

  • In the Instances list, in the Maintenance column. If maintenance is scheduled, you see the date and time for when it is scheduled to start. You can filter the instances list using the term Maintenance to find all the instances scheduled for maintenance. The Maintenance column only displays when maintenance is scheduled on one or more instances in the project. If no maintenance is scheduled, the column is hidden.
  • On the Instance details page in the Maintenance pane. If maintenance is scheduled, under Upcoming, you see a date and time for when it is scheduled to start.
  • On the ACTIVITY page in the Cloud Console, you can view a list of instances scheduled for maintenance. If maintenance is scheduled, instances have the message SQL Maintenance and the date and time for when it is scheduled to start.

What happens if the maintenance event is cancelled?

If Cloud SQL cancels a maintenance event, you receive notification that maintenance is cancelled. In rare cases, it might not be possible for Cloud SQL to send a cancellation notification in advance. In this case, you are notified that maintenance was not applied, after the scheduled maintenance window has passed.

You receive a new notification of upcoming maintenance when the maintenance event is rescheduled.

How do I reschedule maintenance?

When you receive a maintenance notification, you have the option to change the maintenance window. For example, if you have a service release launching, you might want to reschedule the maintenance window for a few days before or after your launch.

To reschedule maintenance, go to the Instances list page. The Maintenance column shows dates and times for scheduled maintenance. In the same column, there is a Reschedule button that you use to reschedule maintenance.

You have a few scheduling options for the new maintenance window:

  • Apply updates immediately. You can apply the updates to your instance immediately instead of waiting for the scheduled maintenance window. If you opt to start maintenance immediately, generally, maintenance starts within five minutes.
  • Reschedule to another time. You can postpone a scheduled maintenance event in two ways:

    • Next available window. This moves the maintenance window one week at a time, with a maximum of one rescheduled maintenance per event, per instance.
    • Specific time. This lets you choose any new time within one week of the originally scheduled maintenance.

There are a few things you need to know about rescheduling:

  • You must reschedule maintenance at least 24 hours before the originally scheduled maintenance event happens.

  • You can reschedule maintenance on one or multiple instances in your project. However, you can only reschedule one instance at a time (bulk rescheduling is not available).

  • You can't change a maintenance window more than once, including when trying to apply changes immediately.

  • You can reschedule maintenance to a time that falls within a deny maintenance period, or even outside the maintenance window, as long as the time falls within the one week rescheduling limitation.

To reschedule maintenance now, see rescheduling planned maintenance.

Deny maintenance periods

With deny maintenance periods, you can prevent automatic maintenance from occurring during a specific time period. For example, the end-of-year holiday season is a time of peak load that requires heightened focus on infrastructure stability for many retail businesses. By setting a deny maintenance period from mid-October to mid-January, these businesses can prevent planned upgrades from Cloud SQL during their busiest time of year.

You can have one deny maintenance period at a time for your Cloud SQL instance. You can have a deny maintenance period even if you don't have maintenance windows configured for your instance. Deny maintenance periods can span from one to 90 days.

Deny maintenance periods and relative scheduling are independent features. A deny maintenance period specified on an Earlier instance has no impact in determining the schedule for the Later instance. Notifications are not sent if the maintenance schedule falls within the deny maintenance period for Earlier or Later instances.

When a deny period is set on a primary instance, maintenance to all replicas associated with the primary instance is also denied. As an example, a primary instance located in region A has three read replicas: two in region A and one in Region B. When a deny period is set on the primary instance, maintenance to each of the replicas, including the replica in Region B, will not receive maintenance until the deny period on the primary instance expires.

You can set the deny maintenance period to recur every year by not including the year in the start and end date parameters. If the year is specified, the deny maintenance period is set for only that year.

Learn how to configure a deny maintenance period.

What's next