# Using Amazon RDS Blue/Green Deployments for database updates
A blue/green deployment copies a production database environment to a separate, synchronized staging environment. By using Amazon RDS Blue/Green Deployments, you can make changes to the database in the staging environment without affecting the production environment. For example, you can upgrade the major or minor DB engine version or change database parameters in the staging environment. When you're ready, you can promote the staging environment to be the new production database environment, with downtime typically under one minute.
**Note**
Currently, Blue/Green Deployments are supported for RDS for MariaDB, RDS for MySQL, and RDS for PostgreSQL only. For Amazon Aurora availability, see [Using Amazon Aurora Blue/Green Deployments for database updates](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/blue-green-deployments.html) in the *Amazon Aurora User Guide*.
**Topics**
+ [Overview of Amazon RDS Blue/Green Deployments](blue-green-deployments-overview.md)
+ [Creating a blue/green deployment in Amazon RDS](blue-green-deployments-creating.md)
+ [Viewing a blue/green deployment in Amazon RDS](blue-green-deployments-viewing.md)
+ [Switching a blue/green deployment in Amazon RDS](blue-green-deployments-switching.md)
+ [Deleting a blue/green deployment in Amazon RDS](blue-green-deployments-deleting.md)
# 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 and stays in sync with the current production environment.
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 transition 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 [Overview of Amazon Aurora Blue/Green Deployments](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/blue-green-deployments-overview.html) in the *Amazon Aurora User Guide*.
Under certain conditions, RDS for PostgreSQL uses logical replication instead of physical replication to keep the green environment in sync with the blue environment. For more information, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
Amazon RDS Blue/Green Deployments support Amazon RDS Proxy and smart drivers. These solutions reduce writer node upgrade downtime during switchover by detecting the topology change and redirecting connections to the new production environment without waiting for DNS propagation.
**Topics**
+ [Region and version availability](#blue-green-deployments-region-version-availability)
+ [Benefits of using Amazon RDS Blue/Green Deployments](#blue-green-deployments-benefits)
+ [Workflow of a blue/green deployment](#blue-green-deployments-major-steps)
+ [Authorizing access to Amazon RDS blue/green deployment operations](blue-green-deployments-authorizing-access.md)
+ [Limitations and considerations for Amazon RDS blue/green deployments](blue-green-deployments-considerations.md)
+ [Best practices for Amazon RDS blue/green deployments](blue-green-deployments-best-practices.md)
## Region and version availability
Feature availability and support varies across specific versions of each database engine, and across AWS Regions. For more information, see [Supported Regions and DB engines for Amazon RDS Blue/Green Deployments](Concepts.RDS_Fea_Regions_DB-eng.Feature.BlueGreenDeployments.md).
## 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\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-blue-environment.png)
1. Create the blue/green deployment. For instructions, see [Creating a blue/green deployment in Amazon RDS](blue-green-deployments-creating.md).
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\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment.png)
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 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.
1. Make additional changes to the staging environment, if required. For example, you might 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](Overview.DBInstance.Modifying.md).
1. 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 `1`, and wait for the parameter group to synchronize. Since `read_only` is a dynamic parameter, so a reboot isn't required. Once synchronized, change `read_only` from `1` to `0`. For RDS for PostgreSQL deployments that use logical replication, set the `default_transaction_read_only` parameter to `off` at the session level. For those that use physical replication, you can't enable write operations on the green environment.
1. When ready, switch over to transition the staging environment to be the new production environment. For instructions, see [Switching a blue/green deployment in Amazon RDS](blue-green-deployments-switching.md).
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\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-switchover.png)
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 switched over 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 will 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`.
1. If you no longer need a blue/green deployment, you can delete it. For instructions, see [Deleting a blue/green deployment in Amazon RDS](blue-green-deployments-deleting.md).
After switchover, the previous production environment isn't deleted so that you can use it for regression testing, if necessary.
# Authorizing access to Amazon RDS 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](UsingWithRDS.IAM.md).
The user who creates a blue/green deployment must have permissions to perform the following RDS operations:
+ `rds:CreateBlueGreenDeployment`
+ `rds:AddTagsToResource`
+ `rds:CreateDBInstanceReadReplica`
The user who switches over a blue/green deployment must have permissions to perform the following RDS operations:
+ `rds:SwitchoverBlueGreenDeployment`
+ `rds:ModifyDBInstance`
+ `rds:PromoteReadReplica`
The user who deletes a blue/green deployment must have permissions to perform the following RDS operation:
+ `rds:DeleteBlueGreenDeployment`
+ `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 (\$1) 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](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonrds.html).
# Limitations and considerations for Amazon RDS blue/green deployments
Blue/green deployments in Amazon RDS require careful consideration of factors such as replication slots, resource management, instance sizing, and potential impacts on database performance. The following sections provide guidance to help you optimize your deployment strategy to ensure minimal downtime, seamless transitions, and effective management of your database environment.
**Topics**
+ [Limitations for blue/green deployments](#blue-green-deployments-limitations)
+ [Considerations for blue/green deployments](#blue-green-deployments-consider)
## Limitations for blue/green deployments
The following limitations apply to blue/green deployments.
**Topics**
+ [General limitations for blue/green deployments](#blue-green-deployments-limitations-general)
+ [RDS for MySQL limitations for blue/green deployments](#blue-green-deployments-limitations-mysql)
+ [RDS for PostgreSQL limitations for blue/green deployments with physical replication](#blue-green-deployments-limitations-postgres-physical)
+ [RDS for PostgreSQL limitations for blue/green deployments with logical replication](#blue-green-deployments-limitations-postgres-logical)
### General limitations for blue/green deployments
The following general limitations apply to blue/green deployments:
+ Blue/green deployments don't support managing master user passwords with AWS Secrets Manager.
+ If dedicated log volume (DLV) is enabled on the blue database, it must be enabled on *all* DB instances, including read replicas.
+ 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.
+ You can't change an unencrypted DB instance into an encrypted DB instance. In addition, you can't change an encrypted DB instance into an unencrypted DB instance.
+ You can't change a blue DB instance to a higher engine version than its corresponding green DB instance.
+ The resources in the blue environment and green environment must be in the same AWS account.
+ If you use Amazon RDS Proxy, you must register your blue cluster with the proxy before creating a blue/green deployment. If a blue/green deployment already exists for a given blue cluster, registering that blue cluster to Amazon RDS Proxy will be blocked.
+ Amazon RDS Proxy with blue/green deployments is not supported for Aurora Global Databases.
+ Blue/green deployments aren't supported for the following features:
+ Cascading read replicas
+ Cross-Region read replicas
+ 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 for Amazon RDS](Concepts.MultiAZ.md).
### RDS for MySQL limitations for blue/green deployments
The following limitations apply to RDS for MySQL blue/green deployments:
+ The blue DB instance can't be an external binlog replica.
+ 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](USER_UpgradeDBInstance.Upgrading.md).
+ Blue/green deployments don't support the AWS JDBC Driver for MySQL. For more information, see [Known Limitations](https://github.com/awslabs/aws-mysql-jdbc?tab=readme-ov-file#known-limitations) on GitHub.
### RDS for PostgreSQL limitations for blue/green deployments with physical replication
The following limitations apply to RDS for PostgreSQL blue/green deployments that use physical replication. For an explanation of when blue/green deployments use physical replication instead of logical replication, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
+ After the green environment is created, you can't perform a manual major version upgrade.
+ Blue/green deployments that use physical replication don't support schema changes on the green environment, as it is strictly read-only.
+ The blue DB instance can't be a logical source (publisher) or replica (subscriber).
+ Blue/Green deployments have the following limitations when configuring delayed replication in RDS for PostgreSQL:
+ **Green source instance** — The `recovery_min_apply_delay parameter` is disregarded, even if configured in the parameter group. Any delay settings on the green source instance do not take effect.
+ **Green replica instance** — The `recovery_min_apply_delay parameter` is fully supported and applied to the PostgreSQL configuration file. Delay settings function as expected during the switchover workflow.
+ Delayed replication isn't compatible with RDS Blue/Green deployments for major version upgrades.
### RDS for PostgreSQL limitations for blue/green deployments with logical replication
The following limitations apply to RDS for PostgreSQL blue/green deployments that use logical replication. For an explanation of when blue/green deployments use logical replication instead of physical replication, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
+ [Unlogged](https://www.postgresql.org/docs/16/sql-createtable.html#SQL-CREATETABLE-UNLOGGED) tables aren't replicated to the green environment.
+ The blue DB instance can't be a logical source (publisher) or replica (subscriber).
+ 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.
+ In a blue/green deployment, each database requires a logical replication slot. As the number of databases grows, resource overhead increases and can potentially lead to replication lag, especially if the DB instance isn't sufficiently scaled. The impact depends on factors such as database workload and the number of connections. To mitigate this, consider scaling up your DB instance class or reducing the number of databases on the source instance.
+ The logical replication [apply process](https://www.postgresql.org/docs/current/logical-replication-architecture.html) in the green environment is single-threaded. If the blue environment generates a high volume of write traffic, the green environment might not be able to keep up. This can lead to replication lag or failure, especially for workloads that produce continuous high write throughput. Make sure to test your workloads thoroughly. For scenarios that require major version upgrades and handling high-volume write workloads, consider alternative approaches such as using [AWS Database Migration Service (AWS DMS)](https://docs.aws.amazon.com/dms/latest/userguide/data-migrations.html).
+ Blue/Green deployments have the following limitations when configuring delayed replication in RDS for PostgreSQL:
+ **Green source instance** — The `recovery_min_apply_delay parameter` is disregarded, even if configured in the parameter group. Any delay settings on the green source instance do not take effect.
+ **Green replica instance** — The `recovery_min_apply_delay parameter` is fully supported and applied to the PostgreSQL configuration file. Delay settings function as expected during the switchover workflow.
+ Delayed replication isn't compatible with RDS Blue/Green deployments for major version upgrades.
+ Creating new partitions on partitioned tables isn't supported during blue/green deployments for RDS for PostgreSQL. Creating new partitions involves data definition language (DDL) operations such as `CREATE TABLE`, which aren't replicated from the blue environment to the green environment. However, existing partitioned tables and their data will be replicated to the green environment.
+ The following limitations apply to PostgreSQL extensions:
+ The `pg_partman` extension must be disabled in 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.
+ The `pglogical` and `pgactive` extensions must be disabled on the blue environment when you create a blue/green deployment. After you switch over 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](Appendix.PostgreSQL.CommonDBATasks.pgaudit.basic-setup.md).
#### Logical replication-specific limitations for blue/green deployments
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. For more information, see [Restrictions](https://www.postgresql.org/docs/current/logical-replication-restrictions.html) in the PostgreSQL logical replication documentation.
| 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 must delete the blue/green deployment and all green databases, then recreate it. |
| Data control language (DCL) statements, such as GRANT and REVOKE, aren't replicated from the blue environment to the green environment. | If Amazon RDS PostgreSQL detects an attempt to execute a DCL statement in the blue environment, you will see a warning message. There is no configuration or API available to change this behavior, as it is a limitation of the blue/green deployment process. |
| 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. While a high volume of sequences generally allows the switchover to proceed, an exceptionally large number—such as several hundred thousand—might cause the process to time out before completion. You can increase the switchover timeout to allow more time for synchronization. For more information, see [Switchover timeout](blue-green-deployments-switching.md#blue-green-deployments-switching-timeout). |
| Large objects in the blue environment aren't replicated to the green environment. This includes both existing large objects and any newly created or modified large objects during the blue/green deployment process. | 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**. You must delete the blue/green deployment and all green databases, then recreate it. |
| Materialized views aren’t automatically refreshed in the green environment. | Refreshing materialized views in the blue environment doesn't refresh them in the green environment. After switchover, you can manually refresh them using the [REFRESH MATERIALIZED VIEW](https://www.postgresql.org/docs/current/sql-refreshmaterializedview.html) command, or schedule a refresh. |
| 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 have a primary key or use `REPLICA IDENTITY FULL`. However, only use `REPLICA IDENTITY FULL` if no primary or unique key exists, as it affects replication performance. For more information, see the [PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication-restrictions.html). |
## Considerations for blue/green deployments
Amazon RDS tracks resources in blue/green deployments with the `DbiResourceId` of each resource. This resource ID is an AWS Region-unique, immutable identifier for the resource.
The *resource* ID is separate from the DB ***instance* ID. Each one is listed in the database configuration in the RDS console.
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 you switch over the green resources to be the new production resources, their resource IDs don't match the blue resource IDs that were previously in production.
After you switch over a blue/green deployment, consider updating the resource IDs to those of the newly transitioned 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 AWS CloudTrail](logging-using-cloudtrail.md).
+ 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](USER_PerfInsights.md).
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 transitioned resources when necessary. For more information, see [Identity and access management for Amazon RDS](UsingWithRDS.IAM.md).
+ 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](UsingWithRDS.IAMDBAuth.md), 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](UsingWithRDS.IAMDBAuth.IAMPolicy.md).
+ If you use AWS Backup to manage automated backups of resources in a blue/green deployment, adjust the resource IDs used by AWS Backup after switchover. For more information, see [Using AWS Backup to manage automated backups for Amazon RDS](AutomatedBackups.AWSBackup.md).
+ 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 to a DB instance](USER_RestoreFromSnapshot.md).
+ 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 for Amazon RDS](USER_PIT.md).
+ 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.
+ After you switch over, AWS Database Migration Service (AWS DMS) replication tasks can't resume because the checkpoint from the blue environment is invalid in the green environment. You must recreate the DMS task with a new checkpoint to continue replication.
+ 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.
+ If you use resource tags for access control or operational management, you need to understand that tag changes aren't synchronized between blue and green environments until switchover. When you create a blue/green deployment, tags from the blue environment are copied to the green environment. After creation, any tag modifications that you make to either environment aren't automatically synchronized. During switchover, blue environment tags replace all tags in the green environment. Apply all necessary tags to the blue environment before you create the blue/green deployment, or reapply required tags to the new production environment after switchover. For more information about tags, see [Tagging Amazon RDS resources](USER_Tagging.md).
# Best practices for Amazon RDS blue/green deployments
The following are best practices for blue/green deployments.
**Topics**
+ [General best practices for blue/green deployments](#blue-green-deployments-best-practices-general)
+ [RDS for MySQL best practices for blue/green deployments](#blue-green-deployments-best-practices-mysql)
+ [RDS for MySQL best practices for blue/green deployments](#blue-green-deployments-best-practices-agd)
+ [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md)
## General best practices for blue/green deployments
Consider the following general best practices when you create a blue/green deployment.
+ 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.
+ If you use 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 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](https://dev.mysql.com/doc/refman/8.0/en/replication-features-differing-tables.html) in the MySQL documentation and [Restrictions](https://www.postgresql.org/docs/current/logical-replication-restrictions.html) in the PostgreSQL logical replication documentation.
**Note**
This limitation doesn't apply to RDS for PostgreSQL blue/green deployments that use physical replication. For more information, see [RDS for PostgreSQL limitations for blue/green deployments with physical replication](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres-physical).
+ 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 [Lazy loading and storage initialization for blue/green deployments](blue-green-deployments-creating.md#blue-green-deployments-creating-lazy-loading).
+ When you switch over a blue/green deployment, follow the switchover best practices. For more information, see [Switchover best practices](blue-green-deployments-switching.md#blue-green-deployments-switching-best-practices).
## RDS for MySQL best practices for blue/green deployments
Consider the following best practices when you create a blue/green deployment from an RDS for MySQL DB instance.
+ Avoid using non-transactional storage engines, such as MyISAM, that aren't optimized for replication.
+ Optimize read replicas and the green environment for binary log replication. If supported by your DB engine, enable GTID, parallel, and crash-safe replication to ensure data consistency and durability before you create your blue/green deployment. For more information, see [Using GTID-based replication](mysql-replication-gtid.md).
+ If the green environment experiences replica lag, consider the following:
+ Temporarily set the `innodb_flush_log_at_trx_commit` parameter to `2` in the green DB parameter group. After replication catches up, revert to the default value of `1` before switchover. If an unexpected shutdown or crash occurs with the temporary parameter value, rebuild the green environment to avoid undetected data corruption.
+ To reduce write latency and improve replication throughput, temporarily change green Multi-AZ DB instances to Single-AZ DB instances. Re-enable Multi-AZ right before switchover.
## RDS for MySQL best practices for blue/green deployments
In addition to the above listed general and engine specific best practices, consider the following best practices for RDS for MySQL DB instance
+ Monitor the following CloudWatch metrics to identify periods of low activity in your production environment:
+ `DatabaseConnections`
+ `ActiveTransactions`
Schedule the blue/green switchover during your planned maintenance window or during a period of low activity.
+ Blue/Green switchover duration varies based on your workload and the number of secondary regions. When you initiate a blue/green switchover, the service waits for replica lag to reach zero before proceeding. We recommend checking replica lag before initiating a switchover.
+ If you intend to use a DB parameter or DB Cluster parameter group other than the default one for your green environment, create the desired parameter group with the same name in all secondary regions before initiating the blue/green deployment.
### RDS for PostgreSQL best practices for blue/green deployments
Consider the following best practices when you create a blue/green deployment from an RDS for PostgreSQL DB instance.
**Topics**
+ [RDS for PostgreSQL general best practices for blue/green deployments](#blue-green-deployments-best-practices-postgres-general)
+ [RDS for PostgreSQL best practices for blue/green deployments with physical replication](#blue-green-deployments-best-practices-postgres-physical)
+ [RDS for PostgreSQL best practices for blue/green deployments with logical replication](#blue-green-deployments-best-practices-postgres-logical)
#### RDS for PostgreSQL general best practices for blue/green deployments
Consider the following general best practices when you create a blue/green deployment from an RDS for PostgreSQL DB instance.
+ Update all of your PostgreSQL extensions to the latest version before you create a blue/green deployment. For more information, see [Upgrading PostgreSQL extensions in RDS for PostgreSQL databases](USER_UpgradeDBInstance.PostgreSQL.ExtensionUpgrades.md).
+ Long-running transactions can cause significant replica lag. To reduce replica lag, consider doing the following:
+ Reduce long-running transactions that can be delayed until after the green environment catches up to the blue environment.
+ Reduce bulk operations on the blue environment until after the green environment catches up to the blue environment.
+ Initiate a manual vacuum freeze operation on busy tables prior to creating the blue/green deployment.
+ For PostgreSQL version 12 and higher, disable the `index_cleanup` parameter on large or busy tables to increase the rate of normal maintenance on blue databases. For more information, see [Vacuuming a table as quickly as possible](Appendix.PostgreSQL.CommonDBATasks.Autovacuum.LargeIndexes.md#Appendix.PostgreSQL.CommonDBATasks.Autovacuum.LargeIndexes.Executing).
**Note**
Regularly skipping index cleanup during vacuuming can lead to index bloat, which might degrade scan performance. As a best practice, use this approach only while using a blue/green deployment. Once the deployment is complete, we recommend resuming regular index maintenance and cleanup.
+ Slow replication can cause senders and receivers to restart often, which delays synchronization. To ensure that they remain active, disable timeouts by setting the `wal_sender_timeout` parameter to `0` in the blue environment, and the `wal_receiver_timeout` parameter to `0` in the green environment.
+ To prevent write-ahead log (WAL) segments from being removed from the blue environment, set the `wal_keep_segments` parameter to 15625 for PostgreSQL version 13 and lower. For version 14 and higher, set the `wal_keep_size` parameter too 1 TiB, if there's enough free storage space.
#### RDS for PostgreSQL best practices for blue/green deployments with physical replication
With physical replication, Amazon RDS creates a read replica of the source DB instance. For related parameters, monitoring, tuning, and troubleshooting, see [Working with read replicas for Amazon RDS for PostgreSQL](USER_PostgreSQL.Replication.ReadReplicas.md).
For an explanation of when blue/green deployments use physical replication instead of logical replication, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
#### RDS for PostgreSQL best practices for blue/green deployments with logical replication
Consider the following best practices when you create a blue/green deployment that uses logical replication. For an explanation of when blue/green deployments use logical replication instead of physical replication, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
+ 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. For more information, see the [PostgreSQL documentation](https://www.postgresql.org/docs/13/runtime-config-resource.html#GUC-LOGICAL-DECODING-WORK-MEM).
+ You can monitor transaction overflow being written to disk using the `ReplicationSlotDiskUsage` CloudWatch metric. This metric offers insights into the disk usage of replication slots, helping identify when transaction data exceeds memory capacity and is stored on disk. You can monitor freeable memory with the `FreeableMemory` CloudWatch metric. For more information, see [Amazon CloudWatch instance-level metrics for Amazon RDS](rds-metrics.md#rds-cw-metrics-instance).
+ In RDS for PostgreSQL version 14 and higher, you can monitor the size of logical overflow files using the `[pg\$1stat\$1replication\$1slots](https://www.postgresql.org/docs/14/monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-SLOTS-VIEW)` system view.
+ If you’re using the `aws_s3` extension, 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](postgresql-s3-export-access-bucket.md).
+ Review the performance of your UPDATE and DELETE statements and evaluate whether creating an index on the column used in the WHERE clause can optimize these queries. This can enhance performance when the operations are replayed in the green environment.
+ If you're using triggers, make sure they don't interfere with the creating, updating, and dropping of `pg_catalog.pg_publication`, `pg_catalog.pg_subscription`, and `pg_catalog.pg_replication_slots` objects whose names start with 'rds'.
+ 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 for RDS for PostgreSQL](USER_UpgradeDBInstance.PostgreSQL.MajorVersion.Process.md).
+ Avoid configuring triggers as `ENABLE REPLICA` or `ENABLE ALWAYS` if the trigger is used on the source to manipulate data. Otherwise, the replication system propagates changes and executes the trigger, which leads to duplication.
# PostgreSQL replication methods for blue/green deployments
Amazon RDS for PostgreSQL primarily uses physical replication for blue/green deployments. However, if you request a major version upgrade when you create the blue/green deployment, and your source DB instance runs one of the PostgreSQL versions listed in the table below, Amazon RDS uses logical replication instead.
The following table outlines when Amazon RDS uses physical versus logical replication for PostgreSQL blue/green deployments.
| Source PostgreSQL DB instance version | Upgrade action in blue/green deployment | Replication method |
| --- | --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/blue-green-deployments-replication-type.html) | Major version upgrade(green instance on higher major engine version than blue) | Logical replication |
| All supported versions | Minor version upgrade, or no upgrade(green instance on same major engine version as blue) | Physical replication |
**Note**
Major version upgrades are not supported for blue/green deployments with source RDS for PostgreSQL versions 15.3 and lower, 14.8 and lower, 13.11 and lower, 12.15 and lower, or 11.20 and lower.
For information about the limitations of blue/green deployments that use physical and logical replication, see the following sections:
+ [RDS for PostgreSQL limitations for blue/green deployments with physical replication](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres-physical)
+ [RDS for PostgreSQL limitations for blue/green deployments with logical replication](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres-logical)
# Creating a blue/green deployment in Amazon RDS
When you create a blue/green deployment, you specify the source DB instance to copy in the deployment. The DB instance you choose is the production DB instance, and it becomes the primary DB instance in the blue environment. This DB instance is copied to the green environment, and RDS configures replication from the DB instance in the blue environment to the DB instance in the green environment.
RDS copies the blue environment's topology and features to a staging area. If the blue DB instance has read replicas, they are copied as replicas of the green instance. The allocated storage of all green replicas matches the green primary instance, while other storage parameters are inherited from the blue replicas.
If the blue DB instance is a Multi-AZ DB instance deployment, then the green DB instance is created as a Multi-AZ DB instance deployment.
**Topics**
+ [Preparing for a blue/green deployment](#blue-green-deployments-creating-preparing)
+ [Specifying changes when creating a blue/green deployment](#blue-green-deployments-creating-changes)
+ [Lazy loading and storage initialization for blue/green deployments](#blue-green-deployments-creating-lazy-loading)
+ [Creating a blue/green deployment](#blue-green-deployments-creating-create)
+ [Settings for creating blue/green deployments](#create-blue-green-settings)
## Preparing for a blue/green deployment
There are certain steps you must take before you create a blue/green deployment, depending on the engine that your DB instance is running.
**Topics**
+ [Preparing an RDS for MySQL or RDS for MariaDB DB instance for a blue/green deployment](#blue-green-deployments-creating-preparing-mysql)
+ [Preparing an RDS for PostgreSQL DB instance for a blue/green deployment with physical replication](#blue-green-deployments-creating-preparing-postgres-physical)
+ [Preparing an RDS for PostgreSQL DB instance for a blue/green deployment with logical replication](#blue-green-deployments-creating-preparing-postgres-logical)
### Preparing an RDS for MySQL or RDS for MariaDB DB instance for a blue/green deployment
Before you create a blue/green deployment for an RDS for MySQL or RDS for MariaDB DB instance, you must enable automated backups. For instructions, see [Enabling automated backups](USER_WorkingWithAutomatedBackups.Enabling.md).
### Preparing an RDS for PostgreSQL DB instance for a blue/green deployment with physical replication
Before you create an RDS for PostgreSQL blue/green deployment that uses physical replication, make sure to do the following. For a list of versions that use physical replication versus logical replication, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
+ Enable automated backups on the DB instance. For instructions, see [Enabling automated backups](USER_WorkingWithAutomatedBackups.Enabling.md).
+ Confirm that the DB instance isn't the source or target of external replication. For more information, see [General limitations for blue/green deployments](blue-green-deployments-considerations.md#blue-green-deployments-limitations-general).
### Preparing an RDS for PostgreSQL DB instance for a blue/green deployment with logical replication
Before you create an RDS for PostgreSQL blue/green deployment that uses logical replication, make sure to do the following. For a list of versions that use logical replication versus physical replication, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
+ Associate the instance with a custom DB parameter group with logical replication (`rds.logical_replication`) turned on. Logical replication is required for replication from the blue environment to the green environment. For instructions, see [Modifying parameters in a DB parameter group in Amazon RDS](USER_WorkingWithParamGroups.Modifying.md).
Because blue/green deployments require at least one background worker per database, make sure to tune the following configuration settings according to your workload. For instructions to tune each setting, see [Configuration Settings](https://www.postgresql.org/docs/current/logical-replication-config.html) in the PostgreSQL documentation.
+ `max_replication_slots`
+ `max_wal_senders`
+ `max_logical_replication_workers`
+ `max_worker_processes`
After you enable logical replication and set all configuration options, make sure to reboot the DB instance so that your changes take effect. Blue/green deployments *require* that the DB instance be in sync with the DB parameter group, otherwise creation fails. For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
+ Confirm that the DB instance isn't the source or target of external replication. For more information, see [General limitations for blue/green deployments](blue-green-deployments-considerations.md#blue-green-deployments-limitations-general).
+ Make sure that all tables in the DB instance have a primary key. PostgreSQL logical replication doesn't allow `UPDATE` or `DELETE` operations on tables that don't have a primary key.
+ RDS for PostgreSQL uses PostgreSQL's native logical replication, storing write-ahead logs (WAL) segments on the blue instance until they're replayed on the green environment. Before you create a blue/green deployment, verify that the blue instance has adequate capacity by checking the following metrics:
+ `FreeStorageSpace`
+ `TransactionLogsGeneration`
+ `TransactionLogsDiskUsage`
+ `OldestReplicationSlotLag`
To estimate the additional storage required on the blue instance, monitor the `TransactionLogsGeneration` CloudWatch metric during peak workload periods. For example, if your workload generates 100 GB of WAL data over 24 hours, ensure you have at least 100 GB of extra storage to accommodate one day's worth of WAL segments. For more information, see [Monitoring metrics in an Amazon RDS instance](CHAP_Monitoring.md).
## Specifying changes when creating a blue/green deployment
You can make the following changes to the DB instance in the green environment when you create the blue/green deployment.
You can make other modifications to the DB instance in the green environment after it is deployed. For example, you might specify a higher engine version or a different parameter group.
For information about modifying a DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
**Topics**
+ [Specify a higher engine version](#blue-green-deployments-engine-version)
+ [Specify a different DB parameter group](#blue-green-deployments-parameters)
+ [Modify storage and performance settings](#blue-green-deployments-resize)
+ [Enable RDS Optimized Writes](#blue-green-deployments-db-instance)
+ [Upgrade the storage configuration](#blue-green-deployments-storage)
### Specify a higher engine version
You can specify a higher engine version if you want to test a DB engine upgrade. Upon switchover, the database is upgraded to the major or minor DB engine version that you specify.
### Specify a different DB parameter group
You can test how parameter changes affect the DB instances in the green environment or specify a parameter group for a new major DB engine version in the case of an upgrade.
If you specify a different DB parameter group, the specified DB parameter group is associated with all of the DB instances in the green environment. If you don't specify a different parameter group, each DB instance in the green environment is associated with the parameter group of its corresponding blue DB instance.
### Modify storage and performance settings
Adjust storage and performance settings in the green environment to optimize resource allocation. These settings include allocated storage, provisioned IOPS, storage type, and storage throughput (for gp3 storage).
You can change the storage type of the green DB instance to gp2, gp3, io1, or io2. For gp3 storage, you can also adjust storage throughput to enhance data transfer performance for high-demand workloads, or to reduce costs for less intensive applications. For more information, see [Amazon RDS DB instance storage](CHAP_Storage.md).
You can also choose to increase or decrease allocated storage in the green environment. However, a storage reduction only occurs if the target allocated storage is at least 20% more than the current storage usage. If you decrease the allocated storage, Amazon RDS initiates a storage configuration upgrade. For more information, see [Upgrade the storage configuration](#blue-green-deployments-storage). The minimum target storage is calculated as:
```
Minimum Target Storage = Total Allocated Storage × Current Apparent Utilization × 1.2
```
1. Total Allocated Storage: The storage capacity provisioned for your DB instance, visible in the RDS console.
1. Current Apparent Utilization: The percentage of allocated storage in use. To estimate it, use the `os.fileSys.usedPercent` metric from Performance Insights (Database Insights) or Enhanced Monitoring.
**Note**
Since storage utilization fluctuates over time, we recommend setting the target storage slightly above the calculated minimum to account for potential increases during the reduction process.
If the blue DB instance uses magnetic storage, you must change the green DB instance to a General Purpose or Provisioned IOPS storage type in order to increase or decrease the allocated storage.
### Enable RDS Optimized Writes
You can use a blue/green deployment to upgrade to a DB instance class that supports RDS Optimized Writes. You can only enable RDS Optimized Writes on a database that was *created* with a supported DB instance class. Thus, this option creates a green database that uses a supported DB instance class, which enables you to turn on RDS Optimized Writes on the green DB instance.
If you're upgrading from a DB instance class that doesn't support RDS Optimized Writes to one that does, you must also upgrade the storage configuration of the green DB instance. For more information, see [Upgrade the storage configuration](#blue-green-deployments-storage).
You can only upgrade the DB instance class of the *primary* green DB instance. By default, read replicas in the green environment inherit the DB instance settings from the blue environment. After the green environment is successfully created, you must manually modify the DB instance class of the read replicas in the green environment.
Some instance class upgrades aren't supported depending on the engine version and instance class of the blue DB instance. For more information about DB instance classes, see [DB instance classes](Concepts.DBInstanceClass.md).
### Upgrade the storage configuration
If your blue database isn't on the latest storage configuration, RDS can migrate the green DB instance from the older storage configuration (32-bit file system) to the preferred configuration. You can use RDS Blue/Green Deployments to overcome the scaling limitations on storage and file size for older 32-bit file systems. In addition, this setting changes the storage configuration to be compatible with RDS Optimized Writes if the specified DB instance class supports Optimized Writes.
**Note**
Upgrading the storage configuration is an I/O-intensive operation and leads to longer creation times for blue/green deployments. The storage upgrade process is faster if the blue DB instance uses Provisioned IOPS SSD (io1 or io2 Block Express) storage, and if you provisoned the green environment with an instance size of 4xlarge or larger. Storage upgrades involving General Purpose SSD (gp2) storage can deplete your I/O credit balance, resulting in longer upgrade times. For more information, see [Amazon RDS DB instance storage](CHAP_Storage.md).
During the storage upgrade, the green DB instance is temporarily unavailable, while the blue DB instance remains available. Replication pauses during this time. Monitor storage on the blue instance, and consider scaling if storage reaches 90%, as the green instance automatically scales by 10% after the upgrade.
This option is only available if your blue database is *not* on the latest storage configuration, or if you're changing the DB instance class within the same request. You can only upgrade the storage configuration when initially creating a blue/green deployment.
## Lazy loading and storage initialization for blue/green deployments
When you create a blue/green deployment, Amazon RDS creates the primary DB instance in the green environment by restoring from a DB snapshot. After it's created, the green DB instance and its read replicas continue to load data in the background through a process known as *lazy loading*.
Lazy loading only loads data blocks as applications request them. If you attempt to access data that hasn't been loaded yet, Amazon EBS immediately retrieves it from Amazon S3, while remaining data continues to load in the background. For more information, see [Amazon EBS snapshots](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSSnapshots.html).
To accelerate full volume performance, Amazon RDS provides storage initialization, which reads all blocks in the green environment volume. Amazon EBS proactively downloads blocks from Amazon S3, providing maximum volume performance from the first use. Storage initialization occurs entirely in the background, ensuring no impact on your DB instance availability or ongoing activities, such as patching or upgrades.
Storage initialization is available only for instances in blue/green deployments with `gp2`, `gp3`, `io1`, and `io2` volume types. It supports all instance classes except the t3 and t4 families. If you modify a green DB instance in a Single-AZ deployment to a Multi-AZ DB instance deployment, storage initialization includes the secondary node in the Multi-AZ configuration.
During storage initialization, the instance remains fully available and usable for database operations, though storage might not reach full performance until initialization completes. While the storage initialization is underway, the overall instance status changes to **Storage-initialization**, and the progress indicator reflects the minimum initialization level across all volumes of the DB instance.
Use the console, AWS CLI, or Amazon RDS API to monitor storage initialization.
------
#### [ Console ]
In the AWS Management Console, you see the progress of storage initialization with the DB instance status.
![\[Storage initialization progress indicator for a blue/green deployment\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/storage-initialization-bg.png)
------
#### [ AWS CLI ]
With the AWS CLI, you can monitor storage initialization with the [describe-db-instances](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) command. The `PercentProgress` field in the response shows what percentage of data has been retrieved from Amazon S3.
```
aws rds describe-db-instances --db-instance-identifier my-db-instance
{
"DBInstances": [
{
"DBInstanceIdentifier": "my-db-instance",
"DBInstanceClass": "db.m5.2xlarge",
"Engine": "postgres",
"DBInstanceStatus": "storage-initialization",
...
"PercentProgress": "34"
}
]
}
```
------
#### [ Amazon RDS API ]
With the Amazon RDS API, you retrieve the status of storage initialization by calling the [DescribeDBInstances](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBInstances.html) action.
------
The progress indicator updates as the background initialization job advances, allowing you to track storage readiness before full storage initialization completes. Storage initialization enables optimized performance as your green DB instance becomes fully operational.
## Creating a blue/green deployment
You can create a blue/green deployment using the AWS Management Console, the AWS CLI, or the RDS API.
### Console
**To create a blue/green deployment**
1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. In the navigation pane, choose **Databases**, and then choose the DB instance that you want to copy to a green environment.
1. Choose **Actions**, **Create blue/green deployment**.
The **Create blue/green deployment** page appears.
![\[Create blue/green deployment\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-create.png)
1. Review the blue database identifiers. Make sure that they match the DB instances that you expect in the blue environment. If they don't, choose **Cancel**.
1. For **Blue/green deployment name**, enter a name for your blue/green deployment.
1. In the remaining sections, specify the settings for the green environment. For information about each setting, see [Settings for creating blue/green deployments](#create-blue-green-settings).
You can make other modifications to the databases in the green environment after it is deployed.
1. Choose **Create**.
### AWS CLI
To create a blue/green deployment using the AWS CLI, use the [create-blue-green-deployment](https://docs.aws.amazon.com/cli/latest/reference/rds/create-blue-green-deployment.html) command. For information about all available options, see [Settings for creating blue/green deployments](#create-blue-green-settings).
**Example**
For Linux, macOS, or Unix:
```
aws rds create-blue-green-deployment \
--blue-green-deployment-name my-blue-green-deployment \
--source arn:aws:rds:us-east-2:123456789012:db:mydb1 \
--target-engine-version 8.0.31 \
--target-db-parameter-group-name mydbparametergroup
```
For Windows:
```
aws rds create-blue-green-deployment ^
--blue-green-deployment-name my-blue-green-deployment ^
--source arn:aws:rds:us-east-2:123456789012:db:mydb1 ^
--target-engine-version 8.0.31 ^
--target-db-parameter-group-name mydbparametergroup
```
### RDS API
To create a blue/green deployment by using the Amazon RDS API, use the [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateBlueGreenDeployment.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateBlueGreenDeployment.html) operation. For information about each option, see [Settings for creating blue/green deployments](#create-blue-green-settings).
## Settings for creating blue/green deployments
The following table explains the settings that you can choose when you create a blue/green deployment. For more information about the AWS CLI options, see [create-blue-green-deployment](https://docs.aws.amazon.com/cli/latest/reference/rds/create-blue-green-deployment.html). For more information about the RDS API parameters, see [CreateBlueGreenDeployment](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateBlueGreenDeployment.html).
| Console setting | Setting description | CLI option and RDS API parameter |
| --- | --- | --- |
| **Allocated storage** | The amount of storage to allocate for your green DB instance (in gibibytes). You can choose to increase or decrease the allocated storage. If your blue DB instance uses magnetic (`standard`) storage, you must change the green DB instance to a General Purpose or Provisioned IOPS storage type in order to modify the allocated storage in the green environment. For more information, see [Amazon RDS DB instance storage](CHAP_Storage.md). | **CLI option:** `--target-allocated-storage` **API parameter:** `TargetAllocatedStorage` |
| **Blue/Green Deployment identifier** | A name for the blue/green deployment. | **CLI option:** `--blue-green-deployment-name` **API parameter:** `BlueGreenDeploymentName` |
| Blue database identifier | The identifier of the instance that you want to copy to the green environment. When using the CLI or API, specify the instance Amazon Resource Name (ARN). | **CLI option:** `--source` **API parameter:** `Source` |
| DB parameter group for green databases | A parameter group to associate with the databases in the green environment. | **CLI option:** `--target-db-parameter-group-name` `--target-db-cluster-parameter-group-name` **API parameter:** `TargetDBParameterGroupName` `TargetDBClusterParameterGroupName` |
| Enable Optimized Writes for green database | Enable RDS Optimized Writes on the green primary DB instance. For more information, see [Enable RDS Optimized Writes](#blue-green-deployments-db-instance). If you're changing from a DB instance class that doesn't support Optimized Writes to one that does, you also need to perform a storage configuration upgrade. For more information, see [Upgrade the storage configuration](#blue-green-deployments-storage). | For the CLI and API, specifying a target DB instance class that supports RDS Optimized Writes automatically enables it on the green primary DB instance. |
| **Engine version for green databases** | Upgrade the databases in the green environment to the specified DB engine version. If not specified, each database in the green environment is created with the same engine version as the corresponding DB instance in the blue environment. If you choose an RDS for PostgreSQL DB instance that uses logical replication, review and acknowledge the logical replication limitations. For more information, see [Logical replication-specific limitations for blue/green deployments](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres). | **CLI option:** `--target-engine-version` **RDS API parameter:** `TargetEngineVersion` |
| Green DB instance class | The compute and memory capacity of each DB instance in the green environment, for example `db.m5d.xlarge`. This option is only visible when you enable RDS Optimized Writes for the green database. | **CLI option:** `--target-db-instance-class` **RDS API parameter:** `TargetDBInstanceClass` |
| Provisioned IOPS | The amount of provisioned input/output operations per second (IOPS) to be initially allocated for the green database. This value applies only to the green primary DB instance, not green replicas. | **CLI option:** `--target-iops` **RDS API parameter:** `TargetIops` |
| Storage configuration upgrade | Choose whether to upgrade your storage file system configuration. If you enable this setting, RDS migrates the green database from the old storage file system to the preferred configuration. This option is only available if your blue database is *not* on the latest storage configuration, or if you're enabling RDS Optimized Writes within the same request. You can only upgrade the storage configuration when initially creating a blue/green deployment. For more information, see [Upgrading the storage file system for a DB instance](USER_PIOPS.UpgradeFileSystem.md). | **CLI option:** `--upgrade-target-storage-config` **RDS API parameter:** `UpgradeTargetStorageConfig` |
| Storage throughput | The storage throughput value for the green database. This setting is visible only if you choose General Purpose SSD (gp3) for the storage type. This value applies only to the green primary DB instance, not green replicas. For more information, see [gp3 storage (recommended)](CHAP_Storage.md#gp3-storage). | **CLI option:** `--target-storage-throughput` **RDS API parameter:** `TargetStorageThroughput` |
| Storage type | The storage type for the green database. The following storage types are supported: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/blue-green-deployments-creating.html) This value applies only to the green primary DB instance, not green replicas. For more information, see [Amazon RDS storage types](CHAP_Storage.md#Concepts.Storage). | **CLI option:** `--target-storage-type` **RDS API parameter:** `TargetStorageType` |
# Viewing a blue/green deployment in Amazon RDS
You can view the details about a blue/green deployment using the AWS Management Console, the AWS CLI, or the RDS API.
You can also view and subscribe to events for information about a blue/green deployment. For more information, see [Blue/green deployment events](USER_Events.Messages.md#USER_Events.Messages.BlueGreenDeployments).
## Console
**To view the details about a blue/green deployment**
1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. In the navigation pane, choose **Databases**, and then find the blue/green deployment in the list.
![\[Blue/green deployment in the database list\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-view-db-list.png)
The **Role** value for the blue/green deployment is **Blue/Green Deployment**.
1. Choose the name of blue/green deployment that you want to view to display its details.
Each tab has a section for the blue deployment and a section for the green deployment. For example, on the **Configuration** tab, the DB engine version might be different in the blue environment and in the green environment if you're upgrading the DB engine version in the green environment.
The following image shows an example of the **Connectivity & security** tab:
![\[Blue/green deployment details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-view-details.png)
The **Connectivity & security** tab also includes a section called **Replication**, which shows the current state of replication and replica lag between the blue and green environments. If the replication state is `Replicating`, the blue/green deployment is replicating successfully.
For RDS for PostgreSQL blue/green deployments that use logical replication, the replication state can change to `Replication degraded` if you make unsupported DDL or large object changes in the blue environment. For more information, see [Logical replication-specific limitations for blue/green deployments](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres).
The following image shows an example of the **Configuration** tab:
![\[Blue/green deployment configuration details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-view-config.png)
The following image shows an example of the **Status** tab:
![\[Blue/green deployment status\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-view-status.png)
## AWS CLI
To view the details about a blue/green deployment by using the AWS CLI, use the [describe-blue-green-deployments](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-blue-green-deployments.html) command.
**Example View the details about a blue/green deployment by filtering on its name**
When you use the [describe-blue-green-deployments](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-blue-green-deployments.html) command, you can filter on the `--blue-green-deployment-name`.
The following example shows the details for a blue/green deployment named `my-blue-green-deployment`.
```
aws rds describe-blue-green-deployments \
--filters Name=blue-green-deployment-name,Values=my-blue-green-deployment
```
**Example View the details about a blue/green deployment by specifying its identifier**
When you use the [describe-blue-green-deployments](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-blue-green-deployments.html) command, you can specify the `--blue-green-deployment-identifier` option.
The following example shows the details for a blue/green deployment with the identifier `bgd-1234567890abcdef`.
```
aws rds describe-blue-green-deployments \
--blue-green-deployment-identifier bgd-1234567890abcdef
```
## RDS API
To view the details about a blue/green deployment by using the Amazon RDS API, use the [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeBlueGreenDeployments.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeBlueGreenDeployments.html) operation and specify the `BlueGreenDeploymentIdentifier`.
# Switching a blue/green deployment in Amazon RDS
A *switchover* transitions the green environment to be the new production environment. When the green DB instance has read replicas, they are also transitioned. Before you switch over, production traffic is routed to the DB instance and read replicas in the blue environment. After you switch over, production traffic is routed to the DB instance and read replicas in the green environment.
*Switching over* a blue/green deployment is not the same as *promoting* the green DB instance within the blue/green deployment. If you manually promote the green DB instance by choosing **Promote** from the **Actions** menu, replication between the blue and green environments breaks and the blue/green deployment enters a state of **Invalid configuration**.
**Topics**
+ [Switchover timeout](#blue-green-deployments-switching-timeout)
+ [Switchover guardrails](#blue-green-deployments-switching-guardrails)
+ [Switchover actions](#blue-green-deployments-switching-actions)
+ [Switchover when using Amazon RDS Proxy](#blue-green-deployments-switching-rds-proxy)
+ [Switchover best practices](#blue-green-deployments-switching-best-practices)
+ [Verifying CloudWatch metrics before switchover](#blue-green-deployments-switching-over-cloudwatch)
+ [Monitoring replica lag prior to switchover](#blue-green-deployments-monitor-replica-lag)
+ [Switching over a blue/green deployment](#blue-green-deployments-switching-over)
+ [After switchover](#blue-green-deployments-switching-after)
## Switchover timeout
You can specify a switchover timeout period between 30 seconds and 3,600 seconds (one hour). If the switchover takes longer than the specified duration, then any changes are rolled back and no changes are made to either environment. The default timeout period is 300 seconds (five minutes).
## Switchover guardrails
When you start a switchover, Amazon RDS runs some basic checks to test the readiness of the blue and green environments for switchover. These checks are known as *switchover guardrails*. These switchover guardrails prevent a switchover if the environments aren't ready for it. Therefore, they avoid longer than expected downtime and prevent the loss of data between the blue and green environments that might result if the switchover started.
Amazon RDS runs the following guardrail checks on the green environment:
+ **Replication health** – Checks if green primary DB instance replication status is healthy. The green primary DB instance is a replica of the blue primary DB instance.
+ **Replication lag** – Checks if the replica lag of the green primary DB instance is within allowable limits for switchover. The allowable limits are based on the specified timeout period. Replica lag indicates how far the green primary DB instance is lagging behind its blue primary DB instance. For more information, see [Monitoring replica lag prior to switchover](#blue-green-deployments-monitor-replica-lag).
+ **Active writes** – Makes sure there are no active writes on the green primary DB instance.
Amazon RDS runs the following guardrail checks on the blue environment:
+ **External replication** – For RDS for PostgreSQL, makes sure that the blue environment isn't a self-managed logical source (publisher) or replica (subscriber). If it is, we recommend that you drop the self-managed replication slots and subscriptions across all databases in the blue environment, proceed with switchover, then recreate them to resume replication. For RDS for MySQL and RDS for MariaDB, checks whether the blue database isn't an external binlog replica. If it is, make sure that it is not actively replicating.
+ **Long-running active writes** – Makes sure there are no long-running active writes on the blue primary DB instance because they can increase replica lag.
+ **Long-running DDL statements** – Makes sure there are no long-running DDL statements on the blue primary DB instance because they can increase replica lag.
+ **Unsupported PostgreSQL changes** – For RDS for PostgreSQL blue/green deployments that use logical replication, makes sure that no DDL changes and no additions or modifications of large objects have been performed on the blue environment. For more information, see [Logical replication-specific limitations for blue/green deployments](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres).
If Amazon RDS detects unsupported PostgreSQL changes, it changes the replication state to `Replication degraded` and notifies you that switchover is not available for the blue/green deployment. To proceed with switchover, we recommend that you delete and recreate the blue/green deployment and all green databases. To do so, choose **Actions**, **Delete with green databases**.
## Switchover actions
When you switch over a blue/green deployment, RDS performs the following actions:
1. Runs guardrail checks to verify if the blue and green environments are ready for switchover.
1. Stops new write operations on the primary DB instance in both environments.
1. Drops connections to the DB instances in both environments and doesn't allow new connections.
1. Waits for replication to catch up in the green environment so that the green environment is in sync with the blue environment.
1. Renames the DB instances in the both environments.
RDS renames the DB instances in the green environment to match the corresponding DB instances in the blue environment. For example, assume the name of a DB instance in the blue environment is `mydb`. Also assume the name of the corresponding DB instance in the green environment is `mydb-green-abc123`. During switchover, the name of the DB instance in the green environment is changed to `mydb`.
RDS renames the DB instances in the blue environment by appending `-oldn` to the current name, where `n` is a number. For example, assume the name of a DB instance in the blue environment is `mydb`. After switchover, the DB instance name might be `mydb-old1`.
RDS also renames the endpoints in the green environment to match the corresponding endpoints in the blue environment so that application changes aren't required.
1. Allows connections to databases in both environments.
1. Allows write operations on the primary DB instance in the new production environment.
After switchover, the previous production primary DB instance only allows read operations until you set the `read_only` parameter (for RDS for MySQL) or the `default_transaction_read_only` parameter (for RDS for PostgreSQL) to `0` and reboot the DB instance.
You can monitor the status of a switchover using Amazon EventBridge. For more information, see [Blue/green deployment events](USER_Events.Messages.md#USER_Events.Messages.BlueGreenDeployments).
During switchover, tags from the blue environment replace all tags on resources in the green environment. Any tags that you added directly to green environment resources are overwritten during this process. For more information about tags, see [Tagging Amazon RDS resources](USER_Tagging.md).
If the switchover starts and then stops before finishing for any reason, then any changes are rolled back, and no changes are made to either environment.
## Switchover when using Amazon RDS Proxy
In addition to the above mentioned switchover actions, if the blue cluster is a target of an Amazon RDS Proxy, the following behavior applies during switchover:
+ Switchover Guardrails
+ Amazon RDS runs additional guardrail checks to validate that the proxy can successfully reach both blue and green environments and is ready for switchover.
+ Application Traffic Routing During Switchover
+ During switchover, the Blue database enters read-only mode before Green environment is promoted. Amazon RDS Proxy continues routing connections to the blue database during this transitional period.
+ Write operations on RDS for MySQL and RDS for MariaDB during this period may return read-only errors. For example, `1290 (HY000): The MySQL server is running with the --read-only option` so it cannot execute this statement. On RDS for PostgreSQL, read and write queries will return `AdminShutdown: terminating connection due to administrator command`.
+ Once the switchover is detected, the proxy routes traffic to the newly promoted green environment.
+ When the Green environment is promoted as the new writer, existing connections to the proxy are dropped. Applications must re-establish connections after the promotion is complete.
+ You can review CloudWatch logs for Amazon RDS Proxy to see when this transitional behavior occurred.
+ RDS Proxy API Behavior
+ Proxy APIs such as `describe-db-proxy-targets` reflect the updated targets only after the switchover is fully complete, even though traffic routing occurs earlier.
## Switchover best practices
Before you switch over, we strongly recommend that you adhere to best practices by completing the following tasks:
+ Thoroughly test the resources in the green environment. Make sure they function properly and efficiently.
+ Monitor relevant Amazon CloudWatch metrics. For more information, see [Verifying CloudWatch metrics before switchover](#blue-green-deployments-switching-over-cloudwatch).
+ Identify the best time for the switchover.
During the switchover, writes are cut off from databases in both environments. Identify a time when traffic is lowest on your production environment. Long-running transactions, such as active DDLs, can increase your switchover time, resulting in longer downtime for your production workloads.
If there's a large number of connections on your DB instances, consider manually reducing them to the minimum amount necessary for your application before you switch over the blue/green deployment. One way to achieve this is to create a script that monitors the status of the blue/green deployment and starts cleaning up connections when it detects that the status has changed to `SWITCHOVER_IN_PROGRESS`.
+ Make sure the DB instances in both environments are in `Available` state.
+ Make sure the primary DB instance in the green environment is healthy and replicating.
+ Make sure that your network and client configurations don’t increase the DNS cache Time-To-Live (TTL) beyond five seconds, which is the default for RDS DNS zones. Otherwise, applications will continue to send write traffic to the blue environment after switchover.
+ Make sure data loading is complete before switching over. For more information, see [Lazy loading and storage initialization for blue/green deployments](blue-green-deployments-creating.md#blue-green-deployments-creating-lazy-loading).
+ For RDS for PostgreSQL blue/green deployments that use logical replication, do the following:
+ Review the logical replication limitations and take any required actions prior to switchover. For more information, see [Logical replication-specific limitations for blue/green deployments](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres).
+ Run the `ANALYZE` operation to refresh the `pg_statistics` table. This reduces the risk of performance issues after switchover.
+ Before initiating a blue/green deployment switchover, verify that your application does not override the `default_transaction_read_only` parameter at the session level. During switchover, this parameter is set to `on` on the green environment writer to prevent writes until promotion completes. If your application or transactions override this configuration to `off`, your application may write data to the green environment during the switchover process. In the event the switchover has to roll back, these writes are not available in the blue environment, requiring you to manually resolve the data inconsistencies. We strongly recommend auditing your application queries to ensure they respect the `default_transaction_read_only` setting before proceeding with switchover.
**Note**
During a switchover, you can't modify any DB instances included in the switchover.
## Verifying CloudWatch metrics before switchover
Before you switch over a blue/green deployment, we recommend that you check the value of the following metric within Amazon CloudWatch.
+ `DatabaseConnections` – Use this metric to estimate the level of activity on the blue/green deployment, and make sure that the value is at an acceptable level for your deployment before you switch over. If Performance Insights is turned on, `DBLoad` is a more accurate metric.
For more information, see [Amazon CloudWatch metrics for Amazon RDS](rds-metrics.md).
## Monitoring replica lag prior to switchover
Before you switch over a blue/green deployment, make sure that replica lag is close to zero in order to reduce downtime.
### RDS for MySQL and RDS for MariaDB
For MySQL and MariaDB blue/green deployments, check the `ReplicaLag` CloudWatch metric in the green environment to identify the current replica lag. For more information, see [Diagnosing and resolving lag between read replicas](CHAP_Troubleshooting.md#CHAP_Troubleshooting.MySQL.ReplicaLag).
### RDS for PostgreSQL
For PostgreSQL blue/green deployments that use physical replication, see [Monitoring and tuning the replication process](USER_PostgreSQL.Replication.ReadReplicas.Monitor.md) for instructions to identify the current replica lag.
For PostgreSQL blue/green deployments that use logical replication, check the `OldestReplicationSlotLag` CloudWatch metric in the blue environment to identify the current replica lag. For more information, see [Amazon CloudWatch instance-level metrics for Amazon RDS](rds-metrics.md#rds-cw-metrics-instance).
In addition, you can run the following SQL query in the blue environment:
```
SELECT slot_name,
confirmed_flush_lsn as flushed,
pg_current_wal_lsn(),
(pg_current_wal_lsn() - confirmed_flush_lsn) AS lsn_distance
FROM pg_catalog.pg_replication_slots
WHERE slot_type = 'logical';
slot_name | flushed | pg_current_wal_lsn | lsn_distance
-----------------+---------------+--------------------+------------
logical_replica1 | 47D97/CF32980 | 47D97/CF3BAC8 | 37192
```
The `confirmed_flush_lsn` represents the last log sequence number (LSN) that was sent to the replica. The `pg_current_wal_lsn` represents where the database is now. An `lsn_distance` of 0 means that the replica is caught up.
For an explanation of when blue/green deployments use physical replication versus logical replication, see [PostgreSQL replication methods for blue/green deployments](blue-green-deployments-replication-type.md).
## Switching over a blue/green deployment
You can switch over a blue/green deployment using the AWS Management Console, the AWS CLI, or the RDS API.
### Console
**To switch over a blue/green deployment**
1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. In the navigation pane, choose **Databases**, and then choose the blue/green deployment that you want to switch over.
1. For **Actions**, choose **Switch over**.
The **Switch over** page appears.
![\[Switch over blue/green deployment\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-switch-over.png)
1. On the **Switch over** page, review the switchover summary. Make sure the resources in both environments match what you expect. If they don't, choose **Cancel**.
1. For **Timeout settings**, enter the time limit for switchover.
1. If your instance is running RDS for PostgreSQL, review and acknowledge the pre-switchover recommendations. For more information, see [Logical replication-specific limitations for blue/green deployments](blue-green-deployments-considerations.md#blue-green-deployments-limitations-postgres).
1. Choose **Switch over**.
### AWS CLI
To switch over a blue/green deployment by using the AWS CLI, use the [switchover-blue-green-deployment](https://docs.aws.amazon.com/cli/latest/reference/rds/switchover-blue-green-deployment.html) command with the following options:
+ `--blue-green-deployment-identifier` – Specify the resource ID of the blue/green deployment.
+ `--switchover-timeout` – Specify the time limit for the switchover, in seconds. The default is 300.
**Example Switch over a blue/green deployment**
For Linux, macOS, or Unix:
```
aws rds switchover-blue-green-deployment \
--blue-green-deployment-identifier bgd-1234567890abcdef \
--switchover-timeout 600
```
For Windows:
```
aws rds switchover-blue-green-deployment ^
--blue-green-deployment-identifier bgd-1234567890abcdef ^
--switchover-timeout 600
```
### RDS API
To switch over a blue/green deployment by using the Amazon RDS API, use the [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_SwitchoverBlueGreenDeployment.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_SwitchoverBlueGreenDeployment.html) operation with the following parameters:
+ `BlueGreenDeploymentIdentifier` – Specify the resource ID of the blue/green deployment.
+ `SwitchoverTimeout` – Specify the time limit for the switchover, in seconds. The default is 300.
## After switchover
After a switchover, the DB instances in the previous blue environment are retained. Standard costs apply to these resources. Replication between the blue and green environments stops.
RDS renames the DB instances in the blue environment by appending `-oldn` to the current resource name, where `n` is a number. The DB instances in the old blue environment are read-only until you set the `read_only` parameter (for RDS for MySQL) or the `default_transaction_read_only` parameter (for RDS for PostgreSQL) to `0`. RDS names the DB instances in the green environment `-newn`.
If you delete the blue/green deployment resource, RDS retains the `-oldn` and `-newn` resources.
![\[After switching over a blue/green deployment\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-after-switchover.png)
### Updating the parent node for consumers
RDS offers fully managed read replicas. However, it also provides the option to set up self-managed replicas, also known as *external replicas.* External replicas allow you to use third-party resources as replication targets.
After you switch over an RDS for MariaDB or RDS for MySQL blue/green deployment, if the blue DB instance had any external replicas or binary log consumers prior to switchover, you must update their parent node after switchover in order to maintain replication continuity.
**To update the parent node**
1. After switchover, the DB instance that was previously in the green environment emits an event that contains the master log file name and master log position. To locate the event, navigate to the RDS console and choose **Events** from the left navigation pane.
1. Filter by events where the source is the name of the old green DB instance, before switchover.
1. Locate the event that contains the binary log coordinates. The event message is similar to: `Binary log coordinates in green environment after switchover: file mysql-bin-changelog.000003 and position 40134574`.
1. Make sure that the consumer or replica has applied all binary logs from the old blue environment. Then, use the provided binary log coordinates to resume replication on the consumers. For example, if you're running a MySQL replica on EC2, you can use the following commands:
**MySQL 8.0.22 and lower major and minor versions**
```
CHANGE MASTER TO MASTER_HOST='{new-writer-endpoint}', MASTER_LOG_FILE='mysql-bin-changelog.000003', MASTER_LOG_POS=40134574;
```
**MySQL 8.0.23 and higher major and minor versions**
```
CHANGE REPLICATION SOURCE TO SOURCE_HOST='{new-writer-endpoint}', SOURCE_LOG_FILE='mysql-bin-changelog.000003', SOURCE_LOG_POS=40134574;
```
If the consumer is another RDS for MySQL or RDS for MariaDB DB instance, run the following stored procedures in order:
1. [mysql.rds\$1stop\$1replication](mysql-stored-proc-replicating.md#mysql_rds_stop_replication)
1. [mysql.rds\$1reset\$1external\$1master](mysql-stored-proc-replicating.md#mysql_rds_reset_external_master) (for version 8.0 and lower) or [mysql\$1rds\$1reset\$1external\$1source](mysql-stored-proc-replicating.md#mysql_rds_reset_external_source) (for version 8.4 and higher)
1. [mysql.rds\$1set\$1external\$1master](mysql-stored-proc-replicating.md#mysql_rds_set_external_master) (for version 8.0 and lower) or [mysql\$1rds\$1set\$1external\$1source](mysql-stored-proc-replicating.md#mysql_rds_set_external_source) (for version 8.4 and higher)
1. [mysql.rds\$1start\$1replication](mysql-stored-proc-replicating.md#mysql_rds_start_replication)
# Deleting a blue/green deployment in Amazon RDS
You can delete a blue/green deployment before or after you switch it over.
When you delete a blue/green deployment before switching it over, Amazon RDS optionally deletes the DB instances in the green environment:
+ If you choose to delete the DB instances in the green environment (`--delete-target`), they must have deletion protection turned off.
+ If you don't delete the DB instances in the green environment (`--no-delete-target`), the instances are retained, but they're no longer part of a blue/green deployment. For RDS for MySQL, replication continues between the environments. For RDS for PostgreSQL, the green environment is promoted to a standalone environment, so replication stops.
The option to delete the green databases isn't available in the console after [switchover](blue-green-deployments-switching.md). When you delete blue/green deployments using the AWS CLI, you can't specify the `--delete-target` option if the deployment [status](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_BlueGreenDeployment.html) is `SWITCHOVER_COMPLETED`.
**Important**
Deleting a blue/green deployment doesn't affect the blue environment.
You can delete a blue/green deployment using the AWS Management Console, the AWS CLI, or the RDS API.
## Console
**To delete a blue/green deployment**
1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. In the navigation pane, choose **Databases**, and then choose the blue/green deployment that you want to delete.
1. For **Actions**, choose **Delete**.
The **Delete blue/green deployment?** window appears.
![\[Delete blue/green deployment\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/blue-green-deployment-delete.png)
To delete the green databases, select **Delete the green databases in this blue/green deployment**.
1. Enter **delete me** in the box.
1. Choose **Delete**.
## AWS CLI
To delete a blue/green deployment by using the AWS CLI, use the [delete-blue-green-deployment](https://docs.aws.amazon.com/cli/latest/reference/rds/delete-blue-green-deployment.html) command with the following options:
+ `--blue-green-deployment-identifier` – The resource ID of the blue/green deployment to be deleted.
+ `--delete-target` – Specifies that the DB instances in the green environment are deleted. You can't specify this option if the blue/green deployment has a status of `SWITCHOVER_COMPLETED`.
+ `--no-delete-target` – Specifies that the DB instances in the green environment are retained.
**Example Delete a blue/green deployment and the DB instances in the green environment**
For Linux, macOS, or Unix:
```
aws rds delete-blue-green-deployment \
--blue-green-deployment-identifier bgd-1234567890abcdef \
--delete-target
```
For Windows:
```
aws rds delete-blue-green-deployment ^
--blue-green-deployment-identifier bgd-1234567890abcdef ^
--delete-target
```
**Example Delete a blue/green deployment but retain the DB instances in the green environment**
For Linux, macOS, or Unix:
```
aws rds delete-blue-green-deployment \
--blue-green-deployment-identifier bgd-1234567890abcdef \
--no-delete-target
```
For Windows:
```
aws rds delete-blue-green-deployment ^
--blue-green-deployment-identifier bgd-1234567890abcdef ^
--no-delete-target
```
## RDS API
To delete a blue/green deployment by using the Amazon RDS API, use the [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeleteBlueGreenDeployment.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeleteBlueGreenDeployment.html) operation with the following parameters:
+ `BlueGreenDeploymentIdentifier` – The resource ID of the blue/green deployment to be deleted.
+ `DeleteTarget` – Specify `TRUE` to delete the DB instances in the green environment or `FALSE` to retain them. Cannot be `TRUE` if the blue/green deployment has a status of `SWITCHOVER_COMPLETED`.