This page explains how maintenance updates occur on Cloud SQL instances,and how you can control the timing of these updates. To get started, seeView and set maintenance windows.

Overview

As a managed service, Cloud SQL automatically updates instances to ensurethat the underlying hardware, operating system, and database engine arereliable, performant, secure, and up-to-date. Most of these updates areperformed while your Cloud SQL instance is up and running. However, certainsystem updates require a brief service interruption to be performed.These updates are calledmaintenance.

Maintenance updates the database engine, and in some cases, the operating system.Because these updates require the instance to be restarted,they incur some downtime. Maintenance updates deliver the following benefits:

• Cloud SQL features. To launch new features, the database engineis updated and new plugins to the database are installed.

• Database version upgrades. The database software provider that developsPostgreSQL releases new minor versionsseveral times a year. With each new version come bug fixes, security patches,performance enhancements, and new database features. You can find the latestminor version that Cloud SQL for PostgreSQL supports by reviewingrelease notes orDatabase versions and version policies.Cloud SQL instances are upgraded to the latest database versionshortly after release, so that you benefit from running the latest databasesoftware.

• Operating system patches. We continuously monitor for newly identifiedsecurity vulnerabilities in the operating system. Upon discovery, we patchthe operating system to protect you from new risks.

Maintenance impact

ForCloud SQL Enterprise Plus edition, Cloud SQL offersnear-zero downtime planned maintenance.

Cloud SQL schedules a maintenance update event typically once every fewmonths. The maintenance update can take approximately 5 to 10 minutes foreach instance. If the instance has read replicas, then the overall duration ofthe maintenance update can take longer. However, during the maintenance updateevent, each Cloud SQL Enterprise edition instance loses connectivity for less than30seconds on average. Downtime might be higher for an instance that is undergoinghigh amounts of activity during the maintenance update event or has a very large dataset.

You can take steps to ensure that maintenance has as little impact as possibleon your operations by using ourmaintenance settingsand by making your systemsresilient to transient errors.

In addition, if disk usage on the instance is higher than 97%, thenCloud SQL skips the maintenance update for the instance.

Near-zero downtime planned maintenance

With near-zero downtime planned maintenance, Cloud SQL Enterprise Plus edition instancestypically lose connectivity for less than 1 second during planned maintenance.

The downtime might be higher for instances that have high activityduring the maintenance.

Prerequisites and constraints

• The number of read replicas on your Cloud SQL for PostgreSQL Enterprise Plus edition instances mustbe less than the value set for themax_wal_senders andmax_replication_slots flags. For more information, seeconfigure database flags.

• If you are usingCloud SQL Auth ProxyorCloud SQL Language Connectors, ensurethat they are updated to their latest version.

• Any unlogged tables will be empty after planned maintenance.

• During maintenance, the database logs will have messages from two different VMs.
• If a DDL is issued during the planned maintenance, the changes might have acreation or modification timestamp that is after the maintenance timestamp.

Simulate near-zero downtime planned maintenance

To test the planned maintenance downtime of your Cloud SQL Enterprise Plus edition primaryinstance without updating your database instance, you can simulatenear-zero downtime planned maintenance.

To do this, invoke the simulation of a maintenance event on aCloud SQL Enterprise Plus edition instance that is eligible for near-zero downtime plannedmaintenance. The simulation request results in an instance update operation tothe same maintenance version before the operation.

You can perform the simulation even if you have a maintenance update pendingon the instance. The instance version remains the same throughout the simulation.

To simulate a near-zero downtime planned maintenance event, use the followinggcloud CLI command:

gcloudsqlinstancespatchINSTANCE_NAME--simulate-maintenance-event

ReplaceINSTANCE_NAME with the name of the instance where youwant to run the simulated maintenance event.

Maintenance settings

Cloud SQL offers you the ability to configure maintenance updatesthrough a set of maintenance settings.

You can configure maintenance to be scheduled at times when brief downtimecauses the lowest impact to your applications. For each Cloud SQL instance,you can configure the following:

• Maintenance timing (previouslyOrder of update). The week of the rolloutperiod to update your Cloud SQL instance. You have the following options:

  • Any: the maintenance update can happen at any time, but typically happens within Week 1.
  • Week 1: the maintenance happens 7 to 14 days after the maintenance notification is sent out.
  • Week 2: the maintenance update happens 15 to 21 days after the notification is sent out.
  • Week 5: the maintenance update happens 35 to 42 days after the notification is sent out.

  You set the schedule of the maintenance update when youconfigure a maintenance window.

• Maintenance window. The day of the week and the hour in whichCloud SQL schedules maintenance. Maintenance windows last for onehour. Learnhow to configure a maintenance window.

• Deny maintenance period. A block of days in which Cloud SQLdoes not schedule maintenance. You can set a deny maintenance period for up to 90 dayslong. Learnhow to configure a deny maintenance period.

Default maintenance windows

If you don't set a maintenance window, then Cloud SQL updates your instance inthe following default windows according to your instance's time zone:

• Weekday window (Monday to Friday): 10 PM to 6 AM
• Weekend window: Friday, 10 PM to Monday, 6 AM

Maintenance example

Assume you are a developer at a retailer managing a shoppingcart service. You have one Cloud SQL instance for a production environmentand a second for a staging environment. You want maintenance tooccur at the time when your instance handles the lowest amount of traffic,which is around midnight on Sundays. You also want to skipmaintenance during your busy end-of-year holiday shopping season.

In this case, you set your production instance's maintenance settings to:

• Maintenance window: Sundays between 12:00AM and 1:00AM ET
• Maintenance timing:Week 2
• Deny maintenance period: November 1 through January 15.

The maintenance settings for your staging environment would be identical, exceptthe maintenance timing is set toWeek 2. This ensures you can runoperational acceptance tests for a maintenance release in staging at least sevendays before maintenance rolls out to production. If something goeswrong in the staging environment, you have time to diagnose and fix the issue or set up a deny maintenance periodthat your production environment is unaffected.

Upcoming maintenance notifications

You can have a notification about upcoming maintenance sent to your email atleast one week before maintenance is scheduled. If youwant to set an email filter for notifications, the email title isUpcomingmaintenance for your Cloud SQL instanceinstancename.

Notifications for maintenance aren't sent out by default. You need toopt in to maintenance notifications.Before you can receive notifications, you must also select a maintenance window.

Notifications are sent to the email address associated with your Google Account. It's notpossible to configure a custom email alias (for instance, a team email alias).

You opt into maintenance notifications for all Cloud SQL instances thathave maintenance windows in a given project. You receive one notification perinstance. Upcoming maintenance notifications are not sent out for read replicas.

• In theInstances list, in theMaintenance column. If maintenance isscheduled, you see the date and time for when it is scheduled to start. Youcan filter the instances list using the termMaintenance to find all theinstances scheduled for maintenance. TheMaintenance column only displayswhen maintenance is scheduled on one or more instances in the project. If nomaintenance is scheduled, the column is hidden.
• On theInstance details page in theMaintenance pane. If maintenanceis scheduled, underUpcoming, you see a date and time for when it isscheduled to start.

• On theLogs explorer page in the Google Cloud console.Use theAll logs name drop-down to search formaintenance-events, thenclickApply. If maintenance is scheduled for an instance, then thelog shows the name of the instance and its scheduled maintenance start time.

  Note: If theActivity information is not found on the Logs Explorer page status message appears in theACTIVITY page, make sure you have theresourcemanager.projects.get permission assigned to you. For more information about assigning permissions, seeRoles and permissions.

Other maintenance notifications

When you opt in to receive maintenance notifications, you will be notified ofcertain events:

• Upcoming scheduled maintenance
• Started maintenance
• Completed maintenance
• Canceled maintenance

Reschedule maintenance

If you have a maintenance window for your instance, then you can reschedule the maintenance update up to 24 hours before the maintenance update is scheduled to occur. For example, if you are launching a new service during your scheduled maintenance window, then you might want to postpone the maintenance update to a few days after your launch.

There are some limits to rescheduling maintenance updates.After Cloud SQL sends out the notification email,Cloud SQL performs the maintenance update withina seven-week time period to avoid any overlap with thenext Cloud SQL maintenance update.For example, if you select a maintenance timing of Week 1or Week 2, then you can reschedule the maintenance update up to a maximum of 4 weeks (28 days) after the originally scheduled date. If you set your instance to a maintenance timing of Week 5, then you can only reschedule the maintenance event up to a maximum of one week (7 days) after the original date. You can reschedule maintenance multiple times as long as the rescheduled maintenance event is within the rescheduling duration defined by the maintenance timing that you configured for your instance.

For all other limitations, seeReschedule limitations.

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

• Apply updates immediately. You can apply the update toyour instance immediately instead of waiting for the scheduled maintenancewindow. In this case, maintenance generally starts within five minutes.

• Reschedule to another time. You can postpone a scheduled maintenanceevent in two ways:

  • Next available window. This option defers maintenance to the next available maintenance window following the current scheduled maintenance time, which is typically one week later.
  • Specific time. This option lets you choose a specific time the rescheduling duration defined by the maintenance timing that you configured for your instance.
    • 28 days if you select Week 1 or Week 2 maintenance timing
    • 7 days if you select Week 5 maintenance timing

For instructions on how to reschedule maintenance, seeReschedule planned maintenance.

How maintenance works

To keep maintenance brief, Cloud SQL uses a maintenance failoverworkflow that largely resembles ourautomatic failover workflow for highly available instances.

In short, these are the steps:

1. Set up an updated VM with the new software.
2. Stop the database on the original VM.
3. Switch over the disk and static IP to the updated VM.
4. Start the database on the updated VM.

Step through the following tabs to see details of the workflow, including pre- andpost-maintenance.

Minimize the impact of maintenance

In general, Google Cloud recommends that users running applications in thecloud make their systems resilient to transient errors, which are momentaryinter-service communication issues caused by temporary unavailability.Occasional transient errors are unavoidable in the cloud.

Some of the transient errors that occur during maintenance are droppedconnections and failed in-flight transactions. If you design your systems andtune your applications to be resilient to transient errors, you're alsopositioned to minimize impacts due to database maintenance.

To minimize the impact of dropped connections, you can useconnection pools. Whileconnections between the pooler and the database are dropped during maintenance,the connections between the application and the pooler arepreserved. That way, the work of reestablishing the connections is transparentto the application and offloaded to the connection pooler instead.

To reduce the transaction failures, you can limit the number of long-runningtransactions. Rewriting queries to be smaller and more efficient not onlyreduces maintenance downtime, but also improves database performance andreliability.

To recover efficiently from connection drops and transaction failures, you canefficientlymanage your database connections.You can build connection and query retry logic withexponential back-off intoyour applications and connection poolers. In the event that a query fails or aconnection is dropped, the system institutes a wait period before retrying,which increases for each subsequent retry. For example, the system might wait justa few seconds for the first retry, but up to a minute for the fourth retry.Following this pattern ensures that these failures are corrected, withoutoverloading the service.

Other creative solutions can minimize maintenance impacts as well, from usingscripts to warm the database cache after maintenance to streamlining the numberof tables in databases. We recommend following database managementbest practices andoperational guidelines to ensurethat maintenance goes smoothly.

Time-sensitive maintenance

In very rare cases, Cloud SQL might need to schedule maintenance outsideof your maintenance settings to patch severe stability issues or vulnerabilitiesthat are time-sensitive. These updates are delivered rapidly, and Cloud SQLcounts them as downtime against the SLA.

Self-service maintenance

Cloud SQL regularly releases software improvements and patches tosecurity vulnerabilities through new maintenanceversions that you can install on your instances. Cloud SQL maintains aCloud SQL maintenance changelogfor each database engine major version. To learn more, seeCloud SQL maintenance changelogs.

While Cloud SQL schedules maintenance updates once every fewmonths to ensure you have the latest software, you can useself-servicemaintenance to keep your instance up-to-date if:

• You need an update sooner than your next scheduled maintenance event.
• You want to catch up to the latest software after skipping your mostrecent maintenance update.

If you use read replicas, then you can use self-servicemaintenance toupdate all of your read replicas.You specify the primary instance, and the maintenance request updates allof the read replicas of the primary instance to the specified maintenance version.Then the primary instance is updated to the maintenance version.

Maintenance limitations

This section describes the limitations of Cloud SQL maintenance.

Reschedule limitations

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

• You must reschedule maintenance at least 24 hours before the originallyscheduled 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 isnot available).

• You can reschedule maintenance to a time that falls within a deny maintenanceperiod, or even outside the maintenance window, as long as the reschedulingduration is within the time period defined by themaintenance timingthat you configured for your instance.

• If a maintenance operation is in progress, rescheduling is delayed until theoperation is complete.

Deny maintenance period limitations

There are a few things you need to know about deny maintenance periods:

• You can have a deny maintenance period even if you don't havemaintenance windows configured for your instance. Deny maintenance periods canspan from 1 to 90 days.

• The deny maintenance period takes precedence over any scheduled maintenancewindow. If there is a conflict between the timing of a maintenance window andthe deny maintenance period, the deny maintenance period overrides themaintenance window.

• Deny maintenance periods and maintenance timing are independent features. If you create adeny maintenance period for an instance that hasWeek 1 maintenance timing, it has noimpact in determining the scheduled update for an instance withWeek 2 maintenance timing.If a scheduled maintenance update falls within adeny maintenance period, then Cloud SQL doesn't send out a notification for the instances that you have configured with maintenance timing.

• When a deny period is set on a primary instance, maintenance for all replicasassociated with the primary instance is also denied. As an example, a primaryinstance located in region A has three read replicas: two in region A and onein region B. When a deny period is set on the primary instance, maintenance toeach of the replicas, including the replica in region B, does not receivemaintenance until the deny period on the primary instance expires.

• If a deny maintenance period is set after maintenance is scheduled such thatthe deny maintenance period overlaps with the scheduled maintenance time, theupdate is skipped.

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

• You can set multiple deny maintenance periods in a year. We recommend that youavoid chaining deny periods together to skip consecutive scheduled maintenanceevents. Staying current on Cloud SQL maintenance is important to ensurethat your instance operates reliably. Typically, Cloud SQL maintenanceis scheduled once every few months.

• In order to ensure service reliability, Cloud SQL may notify users withinstances running maintenance releases that are more than 12 months old thatthe next maintenance rollout is required.

• When a deny maintenance period ends, regular maintenance behavior resumes.

• Deny maintenance periods don't affect user-triggered operations, such asself-service maintenance.

Maintenance FAQ

• Does maintenance downtime count toward the SLA?
• How does maintenance affect read replicas?
• Can I cancel scheduled maintenance?
• What happens if the maintenance event is canceled?
• Is Cloud SQL maintenance cumulative?
• What happens if the instance is stopped during its scheduled maintenance update?
• How long does self-service maintenance take for allthe read replicas of a primary instance?
• If I have multiple read replicas of my primary instance, can I do self-service maintenance on a single read replica?

Does maintenance downtime count toward the SLA?

Downtime from normal maintenance does not count towards the SLA. However,Cloud SQL counts time-sensitive maintenance downtime against the SLA.

How does maintenance affect read replicas?

• Cloud SQL always maintains read replicas before the primary instance.If the primary instance has a maintenance window, read replicas observethe same maintenance window.
• If your primary instance has multiple read replicas, Cloud SQLmight update some of the replicas simultaneously.
• Read replicas observe the deny maintenance period set for the primaryinstance.

Can I cancel scheduled maintenance?

You can't cancel a scheduled maintenance window, but you canreschedule it. You can also configure adeny maintenance period that overlaps with the scheduledmaintenance time to effectively skip maintenance.

What happens if the maintenance event is canceled?

If Cloud SQL cancels a maintenance event, you receive a notificationthat maintenance is canceled in advance, when possible.

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

Is Cloud SQL maintenance cumulative?

Maintenance updates are cumulative. There's no need to apply each maintenanceupdate that you might have missed. The latest maintenance version is applied inthe next scheduled maintenance update. Or, you can apply the latest maintenanceupdate usingself-service maintenance.

What happens if the instance is stopped during its scheduled maintenance update?

If an instance is stopped during its scheduled maintenance update,then Cloud SQL skips the maintenance update. However,the next time that you restart the instance, Cloud SQL updates theinstance with the latest maintenance update automatically.

How long does self-service maintenance take for all the read replicas of a primary instance?

The amount of time that a self-service maintenance update takes depends on thetotal number of read replicas of your primary instance.To reduce the amount of time that the self-servicemaintenance update might take, you can update a few read replicas individuallyand then perform the update on the primary instance to update the rest of theread replicas.

The second update skips any replicas that already have the targetmaintenance version.

If I have multiple read replicas of my primary instance, can I do self-service maintenance on a single read replica?

Yes, you can perform self-service maintenance on anindividual read replica instance.However, we recommend that you update the rest of the read replicas and primaryinstance to the same maintenance version soon afterwards.We recommend that you operate all the read replicas and primary instance withan identical maintenance version.

What's next

• See how toopt in to maintenance notifications.
• See how toset a maintenance window.
• See how toview maintenance notifications.