Upgrade from Amazon Aurora Serverless v1 to v2 with minimal downtime

January 2024: This post was reviewed and updated for accuracy.

When Amazon Aurora Serverless v1 came out, it was one of the most exciting new features of 2018. The ability to have a relational database without having to worry about paying for idle compute, and without having a poor user experience due to periods of high load with insufficient capacity, was game-changing, and many AWS customers agreed.

Since that time, the Aurora service has evolved significantly. In 2022, we released Aurora Serverless v2, the next step in the evolution of Aurora Serverless. Aurora Serverless v2 brought serverless much closer to feature parity with provisioned Aurora, and enabled many important features that customers were asking for, including Aurora replicas, logical replication, and global databases. However, the migration path from Aurora Serverless v1 to Aurora Serverless v2 was operationally complex, and required non-negligible downtime.

There is a new upgrade path for Aurora Serverless v1 that allows you to go from an Amazon Serverless v1 database to a provisioned Aurora cluster with only a 30-second failover, similar to what would happen if you promoted an Aurora read replica to be the new writer. Then you can use the new blue/green deployment feature to upgrade the database to a version supported by Aurora Serverless v2, and add a serverless instance to your cluster.

It is important to make note of the differences between Aurora Serverless v1 and Aurora Serverless v2 before you consider migrating.

In this post, we walk you through the steps to migrate an existing Aurora Serverless v1 database cluster to Aurora Serverless v2.

Solution overview

For this post, we convert an Amazon Aurora MySQL-Compatible Edition cluster. You can use the same strategy with Amazon Aurora PostgreSQL-Compatible Edition clusters.

For the full documentation of the new feature, refer to Modifying an Aurora Serverless v1 DB cluster.

Prerequisites

The procedure described in this post requires the most recent version of the AWS Command Line Interface (AWS CLI). If you haven’t updated recently, refer to Installing or updating the latest version of the AWS CLI to do so before continuing.

Convert the Aurora Serverless v1 instance to a provisioned Aurora instance

The following screenshot shows the Aurora Serverless v1 database cluster we use for this post, called aurora-mysql-serverless.

To begin, we create a parameter group for the source database cluster. This is required because the blue/green deployment process requires binary logging be enabled. If you already have a custom parameter group, you can continue using it by changing the binlog_format parameter to MIXED, and then skip this step. To create a new parameter group, use the following code:

aws rds create-db-cluster-parameter-group \
 --db-cluster-parameter-group-name aurora-mysql-with-binlogging \
 --description 'Aurora MySQL 5.7 With Binlog Enabled' \
 --db-parameter-group-family aurora-mysql5.7

aws rds modify-db-cluster-parameter-group \
 --db-cluster-parameter-group-name aurora-mysql-with-binlogging \
 --parameters 'ParameterName=binlog_format,ParameterValue=MIXED,ApplyMethod=pending-reboot'

Next, we attach the MySQL 5.7 parameter group to the existing database cluster:

aws rds modify-db-cluster \
 --db-cluster-identifier aurora-mysql-serverless \
 --db-cluster-parameter-group-name aurora-mysql-with-binlogging \
 --apply-immediately

It is important to wait for the parameter group update to complete before proceeding to the next step. After requesting the parameter group update, the cluster will enter modifying state within a minute, emitting an event similar to Scaling DB cluster from 8 capacity units to 8 capacity units for this reason: Apply database parameters.

After this, when the cluster enters available state again, it means that parameter group update has completed and you can proceed to the next step.

To migrate this serverless database cluster to an Aurora provisioned database cluster, run the modify-db-cluster command in a terminal window:

aws rds modify-db-cluster \
 --db-cluster-identifier aurora-mysql-serverless \
 --engine-mode provisioned \
 --allow-engine-mode-change \
 --db-cluster-instance-class db.r5.xlarge \
 --apply-immediately

aws rds wait db-instance-available \
 --db-instance-identifier aurora-mysql-serverless-instance-1

aws rds wait db-cluster-available \
 --db-cluster-identifier aurora-mysql-serverless

The following screenshot shows the updated view on the Databases page.

For this post, we have specified the database cluster name and selected a db.r5.xlarge instance type. For a list of valid instance types for this operation, refer to Modifying an Aurora Serverless v1 DB cluster. You should choose an instance size that suits the expected peak workload during the time it takes to transition to Amazon Serverless v2.

The conversion will take a few minutes, during which time there will be an approximately 30-second failover window while the new provisioned instance is promoted. When the process is complete, your cluster will be converted to a provisioned Aurora database cluster.

Upgrade the database to a version supported by Aurora Serverless v2

Before we can migrate to Amazon Serverless v2, we need to upgrade the database to a version that Amazon Serverless v2 supports. For Amazon Aurora MySQL-Compatible Edition, this means an upgrade from MySQL 5.7 to MySQL 8.0. Doing a major version upgrade requires some planning, and should be done with the proper amount of testing.

We recommend using the new blue/green deployment feature to upgrade databases with minimal downtime. To create a blue/green deployment, use the following command (replace <target-version> with a non-deprecated version id):

aws rds create-blue-green-deployment \
 --source arn:aws:rds:eu-west-1:123456789012:cluster:aurora-mysql-serverless \
 --blue-green-deployment-name aurora-mysql-serverless-green \
 --target-engine-version 8.0.mysql_aurora.<target-version> \
 --target-db-cluster-parameter-group-name default.aurora-mysql8.0

aws rds wait db-cluster-available \
 --db-cluster-identifier GreenClusterID

aws rds wait db-instance-available \
 --db-instance-identifier GreenInstanceID

Make note of the BlueGreenDeploymentIdentifier output value from this command to use in a later step. Additionally, look up the GreenClusterID and GreenInstanceID for the wait commands on the Amazon RDS console. To learn about all the command-line options available for this command, refer to create-blue-green-deployment.

Creating the blue/green deployment and upgrading the green database will take some time, but your application won’t suffer any interruption while this process is progressing. Note that the blue/green deployment will go through two phases: creating a version 5.7 cluster, and then upgrading to version 8.0. You need to wait for both to complete before moving forward.

After the green deployment has been upgraded to the new version and is available, your cluster looks like the following screenshot.

Create an Aurora Serverless v2 replica

Now we need to set the serverless parameters for the cluster to match our requirements using the following command:

aws rds modify-db-cluster \
 --db-cluster-identifier GreenClusterID \
 --serverless-v2-scaling-configuration MinCapacity=4,MaxCapacity=32

For this example, we have chosen a minimum of 4 ACUs and a maximum of 32 ACUs, but you should choose whichever values make sense for your workload.

Now that you have set up your minimum and maximum ACUs, add a serverless instance to the cluster:

aws rds create-db-instance \
 --db-instance-identifier aurora-mysql-serverless-a \
 --db-instance-class db.serverless \
 --engine aurora-mysql \
 --db-cluster-identifier GreenClusterID

aws rds wait db-instance-available \
 --db-instance-identifier aurora-mysql-serverless-a

Fail over to the Aurora Serverless v2 instance

When the new instance is online and ready to go, fail over to it with the following commands:

aws rds failover-db-cluster \
 --db-cluster-identifier GreenClusterID \
 --target-db-instance-identifier aurora-mysql-serverless-a

aws rds wait db-cluster-available \
 --db-cluster-identifier GreenClusterID

The failover process will take a few minutes, during which the green deployment will be unavailable for a period of time, but the blue deployment will remain available to service your application. When the failover is complete, the cluster configuration looks like the following screenshot.

The database cluster is now running with one Aurora Serverless v2 writer and one provisioned Aurora reader. Remove the temporary provisioned instance with the following command:

aws rds delete-db-instance \
 --db-instance-identifier GreenInstanceID

Next, we perform thorough testing of the new database version using the green deployment’s endpoint to make sure that the application doesn’t have any incompatibilities.

When you’re confident your application is happy with the new version, perform the blue/green failover as follows:

aws rds switchover-blue-green-deployment \
 --blue-green-deployment-identifier BlueGreenDeploymentIdentifier \
 --switchover-timeout 120
 
aws rds wait db-cluster-available \
 --db-cluster-identifier aurora-mysql-serverless

aws rds wait db-instance-available \
 --db-instance-identifier aurora-mysql-serverless-a

We replaced BlueGreenDeploymentIdentifier with the actual value obtained from the previous command.

In this example, we have specified that if the system can’t complete the switchover in less than 120 seconds, it should roll back. Refer to switchover-blue-green-deployment for more information about this parameter.

After this is complete, the cluster looks like the following screenshot.

Clean up temporary resources created during the migration

Finally, you can delete the source (formerly blue) instance, the source cluster, and the blue/green deployment itself:

aws rds delete-db-instance \
 --db-instance-identifier OldDatabaseInstanceID
 
aws rds delete-db-cluster \
 --db-cluster-identifier aurora-mysql-serverless-old1 \
 --final-db-snapshot-identifier OldDatabaseClusterID

aws rds delete-blue-green-deployment \
 --blue-green-deployment-identifier BlueGreenDeploymentIdentifier

As before, we replaced BlueGreenDeploymentIdentifier with the actual value obtained when creating the blue/green deployment. The cluster now looks like the following screenshot.

We have successfully migrated an Aurora Serverless v1 database to Aurora Serverless v2 with approximately 30 seconds of downtime.

Conclusion

In this post, we walked you through the process of upgrading an existing Aurora Serverless v1 database to Aurora Serverless v2. This new process allows you to easily migrate from v1 to v2 with minimal application downtime and minimal operational complexity. We encourage you to start planning to migrate your databases from v1 to v2 soon.

About the authors

Tim Gustafson is a Principal Database Specialist Solutions Architect working primarily with open-source database engines.