Overview of Amazon RDS Blue/Green Deployments - Amazon Relational Database Service
BenefitsWorkflowAuthorizing accessConsiderationsBest practicesRegion and version availabilityLimitations
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Overview of Amazon RDS Blue/Green Deployments

By using Amazon RDS Blue/Green Deployments, you can make and test database changes before implementing them in a production environment. A blue/green deployment creates a staging environment that copies the production environment. In a blue/green deployment, the blue environment is the current production environment. The green environment is the staging environment. The staging environment stays in sync with the current production environment using logical replication.

You can make changes to the RDS DB instances in the green environment without affecting production workloads. For example, you can upgrade the major or minor DB engine version, upgrade the underlying file system configuration, or change database parameters in the staging environment. You can thoroughly test changes in the green environment. When ready, you can switch over the environments to promote the green environment to be the new production environment. The switchover typically takes under a minute with no data loss and no need for application changes.

Because the green environment is a copy of the topology of the production environment, the green environment includes the features used by the DB instance. These features include the read replicas, the storage configuration, DB snapshots, automated backups, Performance Insights, and Enhanced Monitoring. If the blue DB instance is a Multi-AZ DB instance deployment, then the green DB instance is also a Multi-AZ DB instance deployment.

Note

Currently, Blue/Green Deployments are supported only for RDS for MariaDB, RDS for MySQL, and RDS for PostgreSQL. For Amazon Aurora availability, see Using Amazon RDS Blue/Green Deployments for database updates in the Amazon Aurora User Guide.

Benefits of using Amazon RDS Blue/Green Deployments

By using Amazon RDS Blue/Green Deployments, you can stay current on security patches, improve database performance, and adopt newer database features with short, predictable downtime. Blue/green deployments reduce the risks and downtime for database updates, such as major or minor engine version upgrades.

Blue/green deployments provide the following benefits:

  • Easily create a production-ready staging environment.

  • Automatically replicate database changes from the production environment to the staging environment.

  • Test database changes in a safe staging environment without affecting the production environment.

  • Stay current with database patches and system updates.

  • Implement and test newer database features.

  • Switch over your staging environment to be the new production environment without changes to your application.

  • Safely switch over through the use of built-in switchover guardrails.

  • Eliminate data loss during switchover.

  • Switch over quickly, typically under a minute depending on your workload.

Workflow of a blue/green deployment

Complete the following major steps when you use a blue/green deployment for database updates.

  1. Identify a production environment that requires updates.

    For example, the production environment in this image has a Multi-AZ DB instance deployment (mydb1) and a read replica (mydb2).

    Production (blue) environment in a blue/green deployment

  2. Create the blue/green deployment. For instructions, see Creating a blue/green deployment.

    The following image shows an example of a blue/green deployment of the production environment from step 1. While creating the blue/green deployment, RDS copies the complete topology and configuration of the primary DB instance to create the green environment. The copied DB instance names are appended with -green-random-characters. The staging environment in the image contains a Multi-AZ DB instance deployment (mydb1-green-abc123) and a read replica (mydb2-green-abc123).

    Blue/green deployment

    When you create the blue/green deployment, you can upgrade your DB engine version and specify a different DB parameter group for the DB instances in the green environment. RDS also configures logical replication from the primary DB instance in the blue environment to the primary DB instance in the green environment.

    After you create the blue/green deployment, the DB instance in the green environment is read-only by default.

  3. Make additional changes to the staging environment, if required.

    For example, you might make schema changes to your database or change the DB instance class used by one or more DB instances in the green environment.

    For information about modifying a DB instance, see Modifying an Amazon RDS DB instance.

  4. Test your staging environment.

    During testing, we recommend that you keep your databases in the green environment read only. Enable write operations on the green environment with caution because they can result in replication conflicts. They can also result in unintended data in the production databases after switchover. To enable write operations for RDS for MySQL, set the read_only parameter to 0, then reboot the DB instance. For RDS for PostgreSQL, set the default_transaction_read_only parameter to off at the session level.

  5. When ready, switch over to promote the staging environment to be the new production environment. For instructions, see Switching a blue/green deployment.

    The switchover results in downtime. The downtime is usually under one minute, but it can be longer depending on your workload.

    The following image shows the DB instances after the switchover.

    DB instances after switching over a blue/green deployment

    After the switchover, the DB instances that were in the green environment become the new production DB instances. The names and endpoints in the current production environment are assigned to the newly promoted production environment, requiring no changes to your application. As a result, your production traffic now flows to the new production environment. The DB instances in the previous blue environment are renamed by appending -oldn to the current name, where n is a number. For example, assume the name of the DB instance in the blue environment is mydb1. After switchover, the DB instance name might be mydb1-old1.

    In the example in the image, the following changes occur during switchover:

    • The green environment Multi-AZ DB instance deployment named mydb1-green-abc123 becomes the production Multi-AZ DB instance deployment named mydb1.

    • The green environment read replica named mydb2-green-abc123 becomes the production read replica mydb2.

    • The blue environment Multi-AZ DB instance deployment named mydb1 becomes mydb1-old1.

    • The blue environment read replica named mydb2 becomes mydb2-old1.

  6. If you no longer need a blue/green deployment, you can delete it. For instructions, see Deleting a blue/green deployment.

    After switchover, the previous production environment isn't deleted so that you can use it for regression testing, if necessary.

Authorizing access to blue/green deployment operations

Users must have the required permissions to perform operations related to blue/green deployments. You can create IAM policies that grant users and roles permission to perform specific API operations on the specified resources they need. You can then attach those policies to the IAM permission sets or roles that require those permissions. For more information, see Identity and access management for Amazon RDS.

The user who creates a blue/green deployment must have permissions to perform the following RDS operations:

  • rds:AddTagsToResource

  • rds:CreateDBInstanceReadReplica

The user who switches over a blue/green deployment must have permissions to perform the following RDS operations:

  • rds:ModifyDBInstance

  • rds:PromoteReadReplica

The user who deletes a blue/green deployment must have permissions to perform the following RDS operation:

  • rds:DeleteDBInstance

Amazon RDS provisions and modifies resources in the staging environment on your behalf. These resources include DB instances that use an internally defined naming convention. Therefore, attached IAM policies can't contain partial resource name patterns such as my-db-prefix-*. Only wildcards (*) are supported. In general, we recommend using resource tags and other supported attributes to control access to these resources, rather than wildcards. For more information, see Actions, resources, and condition keys for Amazon RDS.

Considerations for blue/green deployments

Amazon RDS tracks resources in blue/green deployments with the DbiResourceId of each resource. This resource ID is an Amazon Web Services Region-unique, immutable identifier for the resource.

The resource ID is separate from the DB instance ID:

Create blue/green deployment

The name (instance ID) of a resource changes when you switch over a blue/green deployment, but each resource keeps the same resource ID. For example, a DB instance identifier might be mydb in the blue environment. After switchover, the same DB instance might be renamed to mydb-old1. However, the resource ID of the DB instance doesn't change during switchover. So, when the green resources are promoted to be the new production resources, their resource IDs don't match the blue resource IDs that were previously in production.

After switching over a blue/green deployment, consider updating the resource IDs to those of the newly promoted production resources for integrated features and services that you used with the production resources. Specifically, consider the following updates:

  • If you perform filtering using the RDS API and resource IDs, adjust the resource IDs used in filtering after switchover.

  • If you use CloudTrail for auditing resources, adjust the consumers of the CloudTrail to track the new resource IDs after switchover. For more information, see Monitoring Amazon RDS API calls in Amazon CloudTrail.

  • If you use the Performance Insights API, adjust the resource IDs in calls to the API after switchover. For more information, see Monitoring DB load with Performance Insights on Amazon RDS.

    You can monitor a database with the same name after switchover, but it doesn't contain the data from before the switchover.

  • If you use resource IDs in IAM policies, make sure you add the resource IDs of the newly promoted resources when necessary. For more information, see Identity and access management for Amazon RDS.

  • If you have IAM roles associated with your DB instance, make sure to reassociate them after switchover. Attached roles aren't automatically copied to the green environment.

  • If you authenticate to your DB instance using IAM database authentication, make sure that the IAM policy used for database access has both the blue and the green databases listed under the Resource element of the policy. This is required in order to connect to the green database after switchover. For more information, see Creating and using an IAM policy for IAM database access.

  • If you use Amazon Backup to manage automated backups of resources in a blue/green deployment, adjust the resource IDs used by Amazon Backup after switchover. For more information, see Using Amazon Backup to manage automated backups.

  • If you want to restore a manual or automated DB snapshot for a DB instance that was part of a blue/green deployment, make sure you restore the correct DB snapshot by examining the time when the snapshot was taken. For more information, see Restoring from a DB snapshot.

  • If you want to describe a previous blue environment DB instance automated backup or restore it to a point in time, use the resource ID for the operation.

    Because the name of the DB instance changes during switchover, you can't use its previous name for DescribeDBInstanceAutomatedBackups or RestoreDBInstanceToPointInTime operations.

    For more information, see Restoring a DB instance to a specified time.

  • When you add a read replica to a DB instance in the green environment of a blue/green deployment, the new read replica won't replace a read replica in the blue environment when you switch over. However, the new read replica is retained in the new production environment after switchover.

  • When you delete a DB instance in the green environment of a blue/green deployment, you can't create a new DB instance to replace it in the blue/green deployment.

    If you create a new DB instance with the same name and Amazon Resource Name (ARN) as the deleted DB instance, it has a different DbiResourceId, so it isn't part of the green environment.

    The following behavior results if you delete a DB instance in the green environment:

    • If the DB instance in the blue environment with the same name exists, it won't be switched over to the DB instance in the green environment. This DB instance won't be renamed by adding -oldn to the DB instance name.

    • Any application that points to the DB instance in the blue environment continues to use the same DB instance after switchover.

    The same behavior applies to DB instances and read replicas.

Best practices for blue/green deployments

The following are best practices for blue/green deployments:

General best practices

  • Thoroughly test the DB instances in the green environment before switching over.

  • Keep your databases in the green environment read only. We recommend that you enable write operations on the green environment with caution because they can result in replication conflicts. They can also result in unintended data in the production databases after switchover.

  • When using a blue/green deployment to implement schema changes, make only replication-compatible changes.

    For example, you can add new columns at the end of a table, create indexes, or drop indexes without disrupting replication from the blue deployment to the green deployment. However, schema changes, such as renaming columns or renaming tables, break replication to the green deployment.

    For more information about replication-compatible changes, see Replication with Differing Table Definitions on Source and Replica in the MySQL documentation and Restrictions in the PostgreSQL logical replication documentation.

  • After you create the blue/green deployment, handle lazy loading if necessary. Make sure data loading is complete before switching over. For more information, see Handling lazy loading when you create a blue/green deployment.

  • When you switch over a blue/green deployment, follow the switchover best practices. For more information, see Switchover best practices.

RDS for MySQL best practices

  • Avoid using non-transactional storage engines, such as MyISAM, that aren't optimized for replication.

  • Optimize read replicas for binary log replication.

    For example, if your DB engine version supports it, consider using GTID replication, parallel replication, and crash-safe replication in your production environment before deploying your blue/green deployment. These options promote consistency and durability of your data before you switch over your blue/green deployment. For more information about GTID replication for read replicas, see Using GTID-based replication.

RDS for PostgreSQL best practices

  • If your database has sufficient freeable memory, increase the value of the logical_decoding_work_mem DB parameter in the blue environment. Doing so allows for less decoding on disk and instead uses memory. You can monitor freeable memory with the FreeableMemory CloudWatch metric. For more information, see Amazon CloudWatch instance-level metrics for Amazon RDS.

  • Update all of your PostgreSQL extensions to the latest version before you create a blue/green deployment. For more information, see Upgrading PostgreSQL extensions.

  • If you’re using the aws_s3 extension, make sure to give the green DB instance access to Amazon S3 through an IAM role after the green environment is created. This allows the import and export commands to continue functioning after switchover. For instructions, see Setting up access to an Amazon S3 bucket.

  • If you specify a higher engine version for the green environment, run the ANALYZE operation on all databases to refresh the pg_statistic table. Optimizer statistics aren't transferred during a major version upgrade, so you must regenerate all statistics to avoid performance issues. For additional best practices during major version upgrades, see How to perform a major version upgrade.

Region and version availability

Feature availability and support varies across specific versions of each database engine, and across Amazon Web Services Regions. For more information on version and Region availability with Amazon RDS Blue/Green Deployments, see Blue/Green Deployments.

Limitations for blue/green deployments

The following limitations apply to blue/green deployments.

General limitations for blue/green deployments

The following general limitations apply to blue/green deployments:

  • MySQL versions 8.0.11 through 8.0.13 have a community bug that prevents them from supporting blue/green deployments.

  • The following versions of RDS for PostgreSQL are supported as upgrade source and target versions: 11.21 and higher, 12.16 and higher, 13.12 and higher, 14.9 and higher, and 15.4 and higher. For lower versions, you can perform a minor version upgrade to a supported version.

  • Blue/green deployments don't support managing master user passwords with Amazon Secrets Manager.

  • For RDS for PostgreSQL, unlogged tables aren't replicated to the green environment.

  • For RDS for PostgreSQL, the blue environment DB instance can't be a self-managed logical source (publisher) or replica (subscriber). For RDS for MySQL, the blue environment DB instance can't be an external binlog replica.

  • During switchover, the blue and green environments can't have zero-ETL integrations with Amazon Redshift. You must delete the integration first and switch over, then recreate the integration.

  • The Event Scheduler (event_scheduler parameter) must be disabled on the green environment when you create a blue/green deployment. This prevents events from being generated in the green environment and causing inconsistencies.

  • Blue/green deployments don't support the Amazon JDBC Driver for MySQL. For more information, see Known Limitations on GitHub.

  • Blue/green deployments aren't supported for the following features:

    • Amazon RDS Proxy

    • Cascading read replicas

    • Cross-Region read replicas

    • Amazon CloudFormation

    • Multi-AZ DB cluster deployments

      Blue/green deployments are supported for Multi-AZ DB instance deployments. For more information about Multi-AZ deployments, see Configuring and managing a Multi-AZ deployment.

PostgreSQL extension limitations for blue/green deployments

The following limitations apply to PostgreSQL extensions:

  • The pg_partman extension must be disabled on the blue environment when you create a blue/green deployment. The extension performs DDL operations such as CREATE TABLE, which break logical replication from the blue environment to the green environment.

  • The pg_cron extension must remain disabled on all green databases after the blue/green deployment is created. The extension has background workers that run as superuser and bypass the read-only setting of the green environment, which might cause replication conflicts.

  • If the blue DB instance is configured as the foreign server of a foreign data wrapper (FDW) extension, you must use the instance endpoint name instead of IP addresses. This allows the configuration to remain functional after switchover.

  • The pglogical and pg_active extensions must be disabled on the blue environment when you create a blue/green deployment. After you promote the green environment to be the new production environment, you can enable the extensions again. In addition, the blue database can’t be a logical subscriber of an external instance.

  • If you're using the pgAudit extension, it must remain in the shared libraries (shared_preload_libraries) on the custom DB parameter groups for both the blue and the green DB instances. For more information, see Setting up the pgAudit extension.

Limitations for changes in blue/green deployments

The following are limitations for changes in a blue/green deployment:

  • You can't change an unencrypted DB instance into an encrypted DB instance.

  • You can't change an encrypted DB instance into an unencrypted DB instance.

  • You can't change a blue environment DB instance to a higher engine version than its corresponding green environment DB instance.

  • The resources in the blue environment and green environment must be in the same Amazon Web Services account.

  • For RDS for MySQL, if the source database is associated with a custom option group, you can't specify a major version upgrade when you create the blue/green deployment.

    In this case, you can create a blue/green deployment without specifying a major version upgrade. Then, you can upgrade the database in the green environment. For more information, see Upgrading a DB instance engine version.

PostgreSQL logical replication limitations for blue/green deployments

Blue/green deployments use logical replication to keep the staging environment in sync with the production environment. PostgreSQL has certain restrictions related to logical replication, which translate to limitations when creating blue/green deployments for RDS for PostgreSQL DB instances.

The following table describes logical replication limitations that apply to blue/green deployments for RDS for PostgreSQL.

Limitation Explanation
Data definition language (DDL) statements, such as CREATE TABLE and CREATE SCHEMA, aren't replicated from the blue environment to the green environment.

If Amazon RDS detects a DDL change in the blue environment, your green databases enter a state of Replication degraded.

You receive an event notifying you that DDL changes in the blue environment can't be replicated to the green environment. You must delete the blue/green deployment and all green databases, then recreate it. Otherwise, you won't be able to switch over the blue/green deployment.
NEXTVAL operations on sequence objects aren't synchronized between the blue environment and the green environment.

During switchover, Amazon RDS increments sequence values in the green environment to match those in the blue environment. If you have thousands of sequences, this can delay switchover.
Creation or modification of large objects in the blue environment aren't replicated to the green environment.

If Amazon RDS detects the creation or modification of large objects in the blue environment that are stored in the pg_largeobject system table, your green databases enter a state of Replication degraded.

RDS generates an event notifying you that large object changes in the blue environment can't be replicated to the green environment. You must delete the blue/green deployment and all green databases, then recreate it. Otherwise, you won't be able to switch over the blue/green deployment.

Materialized views aren’t automatically refreshed on the green environment.

Refreshing materialized views in the blue environment doesn't refresh them in the green environment. After switchover, you can schedule a refresh of materialized views.

UPDATE and DELETE operations aren't permitted on tables that don't have a primary key.

Before you create a blue/green deployment, make sure that all tables in the DB instance have a primary key.

For more information, see Restrictions in the PostgreSQL logical replication documentation.