About blue-green deployments in Cloud SQL

This document provides an overview of Cloud SQL blue-green deployments, which let you perform database updates, such as major version upgrades and hardware modifications, while minimizing downtime.

Deployment use cases

You can create a blue-green deployment for the following use cases:

  • Major version upgrade: upgrades your database engine to a later major version when you specify a target database version during deployment creation. Before creating the green instance, Cloud SQL automatically runs the major version upgrade pre-check API to verify compatibility before proceeding with the upgrade workflow.
  • Hardware or configuration changes: stages modifications at your current database version when you create a deployment without specifying a target database version. Use cases include changing machine types (CPU and RAM scaling), testing database flags, or evaluating storage modifications without upgrading the engine version.

How blue-green deployments work

Cloud SQL blue-green deployments provide an automated workflow by staging changes in a temporary secondary environment before switching over live traffic.

During a blue-green deployment, Cloud SQL creates a separate staging environment (green) that mirrors your existing production environment (blue). The service maintains continuous logical replication from blue to green. You can thoroughly test application compatibility and performance on the green environment without affecting production traffic. When you're ready, you trigger a rapid switchover that assigns the green environment to production read and write status with minimal application downtime (typically in seconds).

Components of a blue-green deployment

A blue-green deployment consists of the following components:

  • Blue environment (source): your existing production environment that actively serves application traffic. It consists of the source read and write instance and any associated configuration.
  • Green environment (target): a temporary, isolated staging environment created by Cloud SQL as a clone of the blue environment. The green environment incorporates your requested changes (such as a newer database version) and stays synchronized with the blue environment by using continuous replication. Cloud SQL automatically names the green staging instance using the pattern BLUE_INSTANCE_NAME-green-UNIQUE_ID (where BLUE_INSTANCE_NAME is truncated to a maximum of 48 characters and UNIQUE_ID is an 8-character hexadecimal identifier).
  • Switchover: the planned, user-initiated process of converting the green environment to become the new production read and write instance. During switchover, Cloud SQL swaps connection endpoints so applications connect to the green environment with a brief connection drop (typically in seconds). Expected downtime during switchover varies based on the Cloud SQL edition:

    • Cloud SQL Enterprise Plus edition: switchover downtime is typically sub-second.
    • Cloud SQL Enterprise edition: switchover downtime is typically less than 60 seconds, depending on workload and replication lag.

    Unlike an unplanned failover (which is triggered automatically during an outage), a switchover is a controlled operation used for planned change management.

  • Deletion: the process of removing the blue-green deployment resource. Deletion behavior differs depending on whether switchover has occurred:

    • Before switchover: deleting the deployment removes the green staging instance and the deployment resource. Your blue production instance is unaffected and continues serving traffic.
    • After switchover: deleting the deployment removes the deployment metadata. By default, both the converted instance (green) and the blue instance are retained. You can optionally delete the blue instance to avoid ongoing charges.

Deployment lifecycle and states

A blue-green deployment transitions through four distinct lifecycle phases:

  1. Creation and staging (PROVISIONING): when you request a blue-green deployment, Cloud SQL provisions a temporary green target instance that clones your blue production environment. In the case of a major version upgrade, Cloud SQL also runs the major version upgrade pre-check API to validate database compatibility before proceeding with the upgrade workflow. Cloud SQL applies the requested upgrade or configuration change to the green environment and starts continuous logical replication from blue to green.
  2. Staging verification (SWITCHOVER_READY or SWITCHOVER_NOT_READY): when initial replication finishes, the deployment enters the SWITCHOVER_READY state (or the SWITCHOVER_NOT_READY state if replication is broken or if errors occur). Blue continues serving live production traffic. You connect to green to run validation tests, verify application compatibility, and test query performance.
  3. Switchover execution (SWITCHOVER_IN_PROGRESS or SWITCHOVER_COMPLETED): when you trigger switchover, Cloud SQL runs safety pre-checks, swaps connection endpoints, and sets the green instance as your active production read and write instance (SWITCHOVER_COMPLETED), and transitions the blue instance to a standalone read and write instance. Active read and write operations are routed exclusively to the green instance and logical replication from blue to green is terminated. For more information, see Perform a blue-green deployment switchover.
  4. Deletion (DELETING): when you finish testing or after you verify production operations, you delete the deployment resource. The deletion behavior differs depending on the deployment state:

    • Before switchover (cancel): if you decide not to proceed with the deployment or if verification issues arise, deleting the deployment removes the green staging instance and deletes the deployment metadata. The original blue production instance remains untouched and continues serving traffic without interruption.
    • After switchover (clean up): after switchover completes and you verify operations on the new production instance, deleting the deployment removes the deployment metadata. By default, both the new production instance (green) and the former production instance (blue) are retained as standalone instances. You can optionally specify the --delete-old-source flag (or set delete_old_source_on_destroy = true in Terraform before removing the blue_green_deployment code block) to permanently delete the blue instance and stop incurring charges for it.

    For more information, see Delete a blue-green deployment.

Deployment resource states

When you inspect a blue-green deployment, the state field indicates its current lifecycle status:

  • PROVISIONING: the deployment is being created. For major version upgrades, Cloud SQL runs the pre-check API to validate compatibility before proceeding. Cloud SQL provisions the green environment, applies requested upgrades, and sets up continuous logical replication.
  • SWITCHOVER_READY: the green environment is provisioned, logical replication from blue to green is healthy, and the deployment is ready for switchover.
  • SWITCHOVER_NOT_READY: the deployment is provisioned, but switchover can't be initiated. This occurs if logical replication is broken or stopped, if initial replication hasn't completed, or if a paired node encountered an error.
  • SWITCHOVER_IN_PROGRESS: a switchover operation is actively running. Cloud SQL is swapping connection endpoints and converts the green instance to the active production read and write instance.
  • SWITCHOVER_COMPLETED: the switchover operation has completed successfully. The green instance is now your active production read and write instance, and the blue instance is retained as a standalone read and write instance.
  • DELETING: the deployment is being deleted. If deleting before switchover, Cloud SQL removes the green staging instance and deletes deployment metadata. If deleting after switchover, Cloud SQL removes the deployment metadata and optionally deletes the blue instance if the --delete-old-source flag is specified or if delete_old_source_on_destroy = true is set in Terraform.
  • STATE_UNSPECIFIED: the state of the deployment is unknown.

Manage deployments with Terraform

You can manage the lifecycle of a blue-green deployment declaratively by adding the blue_green_deployment code block to the code block representing the primary google_sql_database_instance resource you want to support:

  1. Create and stage: add the blue_green_deployment code block with the active_environment field set to "SOURCE" and an optional target_database_version field while keeping the top-level database_version field at the current source version.
  2. Inspect and validate: retrieve the connection details for the auto-generated green staging instance from Terraform state. Read the computed attributes on the blue_green_deployment[0] code block (target_instance_name, target_instance_connection_name, and target_instance_ip_addresses) to connect to and test the green instance.
  3. Switch over: convert the green target instance to become the active production instance by updating your primary google_sql_database_instance resource configuration and running the terraform apply command. In the same operation, set the active_environment field in the blue_green_deployment code block to "TARGET" and update the top-level database_version field (along with any other modified instance settings) to match the green instance. For example, the following configuration switches over a deployment that upgrades an instance to MySQL 8.4:

    resource "google_sql_database_instance" "primary" {
      name             = "my-instance"
      region           = "us-central1"
      database_version = "MYSQL_8_4"
    
      # Instance settings matching the green instance
    
      blue_green_deployment {
        deployment_name         = "my-deployment"
        target_database_version = "MYSQL_8_4"
        active_environment      = "TARGET"
      }
    }
    
  4. Clean up or cancel: remove the blue_green_deployment code block from your google_sql_database_instance resource and run the terraform apply command. Removing the code block before switchover cancels the deployment and deletes the green instance. Removing the code block after switchover deletes the deployment metadata and, if delete_old_source_on_destroy = true was previously applied in state, deletes the former blue instance.

Switchover states and readiness

During the switchover, Cloud SQL temporarily blocks new writes to both environments and terminates active connections, which cancels any uncommitted in-flight transactions while preserving all committed transactions. To minimize replication lag and reduce the risk of canceled transactions, perform the switchover when write traffic is lowest on your production environment.

Switchover readiness depends on replication health and node status to protect your production database against data loss or extended downtime:

  • Replication health and lag: if logical replication between blue and green is broken, paused, or fails, the deployment status transitions to SWITCHOVER_NOT_READY. The deployment state and describe output don't report replication lag, and Cloud SQL doesn't evaluate replication lag as a precheck when determining deployment status. However, the switchover operation fails if replication lag is too high when switchover is initiated. To help ensure a successful switchover, make sure that replication lag is minimal before starting the switchover. You can monitor replication lag in Cloud Monitoring (by checking metrics such as replica_lag in the Cloud SQL metrics list) or directly on the green instance. For more information, see Monitor replication lag.
  • Paired node status: in the deploymentMappings field, each paired node reports its own node state (such as PROVISIONED, UPGRADED, UPGRADE_FAILED, SWITCHOVER_IN_PROGRESS, SWITCHOVER_SUCCEEDED, or SWITCHOVER_FAILED). If a paired node encounters an error (UPGRADE_FAILED or SWITCHOVER_FAILED), the overall deployment state transitions to SWITCHOVER_NOT_READY. If a switchover fails, routing remains on the blue instance with zero data loss.
  • Troubleshooting switchover readiness: if your deployment reports the SWITCHOVER_NOT_READY state, check the errorDetail field to diagnose replication or node errors. Before initiating switchover, make sure that replication lag is minimal and verify that active batch DDL operations or long-running write transactions on the blue instance are complete.

Limitations

Review the following limitations before using blue-green deployments:

  • Supported engines, editions, and versions: Cloud SQL for MySQL instances on MySQL 5.7 and later on Cloud SQL Enterprise edition or Cloud SQL Enterprise Plus edition are supported for staging hardware and configuration changes. Major version upgrades are supported from MySQL 8.0 to 8.4. MySQL 8.0.18 isn't supported for blue-green deployments.
  • Unsupported database engines: Cloud SQL for PostgreSQL and Cloud SQL for SQL Server aren't supported.
  • Instances with read replicas: blue-green deployments don't support instances with read replicas.
  • Unsupported network configurations: blue-green deployments don't support Private Service Connect outbound configurations.
  • IAM group authentication: blue-green deployments are incompatible with MySQL IAM group authentication and can cause switchover failures.
  • Network architecture requirement: Cloud SQL instances must use the new network architecture. Instances that use the old network architecture aren't supported.
  • Binary logging requirement: MySQL instances must have automated backups and binary logging enabled to support continuous logical replication to the green environment.
  • Maintenance version requirement: your blue source instance must run the latest maintenance version before you create a blue-green deployment. To check or update your instance maintenance version, see Perform self-service maintenance.
  • Resource availability: instance provisioning during blue-green deployment workflows—including creating the green staging instance and provisioning the standalone blue instance after switchover—can be affected by compute resource constraints in the selected region or zone.
  • Unplanned outages and failover: blue-green deployment switchover is strictly a planned operation that requires a healthy, RUNNING blue source instance. The green staging instance functions as a specialized read replica; like standard read replicas, the green instance can't be used as a failover target during an unplanned outage of the source instance. For automated outage recovery, configure your instance for high availability or use a disaster recovery (DR) replica.
  • Observability and query insights data: during a blue-green deployment, the blue and green instances track observability and query insights data independently. If query insights is enabled on the blue instance, the green instance inherits that configuration and records metrics for workloads that run on the green environment. However, historical observability data isn't copied from the blue instance to the green instance or to the new production instance during switchover. To compare workload performance between the two versions after switchover, keep the former blue instance running to retain access to its historical observability data.

Billing and pricing

There's no additional charge for using blue-green deployments. However, because a complete parallel green environment is provisioned during deployment, you're billed standard rates for both the blue and green instances for the entire duration that both environments exist.

To avoid unnecessary charges, delete the deployment and associated instances:

  • Before switchover: if you cancel the deployment, delete the deployment to remove the green staging instance and stop charges for it.
  • After switchover: delete the deployment and specify the --delete-old-source flag (or set delete_old_source_on_destroy = true in Terraform before removing the blue_green_deployment code block) to permanently delete the blue instance after you verify the new production instance. If you don't delete the blue instance, you continue to be billed for both instances.

What's next