Using a Capacity Reservation with a DB instance

Reserved capacity is used only when you explicitly target the reservation. You reference the reservation by its identifier (dbcr-) or its name when you perform any of the following operations:

• Create a DB instance (CreateDBInstance)

• Create a read replica (CreateDBInstanceReadReplica)

• Restore a DB instance from a snapshot or to a point in time (RestoreDBInstance*)

• Modify a DB instance to move it into a reservation (ModifyDBInstance)

• Start a stopped DB instance (StartDBInstance)

The DB instance's engine, DB instance class, license model (for engines that offer more than one), and Availability Zone must match the reservation, and the reservation must have available capacity in that Availability Zone (the matching entry in AvailableCapacityPerAvailabilityZoneList has an AvailableCapacity greater than 0). If they don't match or no capacity is available, the operation fails with an error that says the Availability Zone doesn't have enough capacity. For a Multi-AZ DB instance, both the primary and the standby Availability Zones must have available capacity.

Console

When you create or restore a DB instance in the Amazon RDS console, in the Capacity reservation section, choose the reservation to launch into.

AWS CLI

Add the --db-capacity-reservation-identifier parameter to the create, restore, or modify command. For example, to create a DB instance that uses a reservation:

aws rds create-db-instance \
    --db-instance-identifier my-db-instance \
    --engine postgres \
    --db-instance-class db.r7g.large \
    --availability-zone us-east-1a \
    --allocated-storage 100 \
    --master-username admin \
    --manage-master-user-password \
    --db-capacity-reservation-identifier my-reservation

The --db-capacity-reservation-identifier parameter accepts either the reservation name or its dbcr- ID.

To restore into a reservation, add the same parameter to the restore command. A snapshot restore takes the engine from the snapshot, but you can override the DB instance class, Availability Zone, and license model – whatever the restored DB instance ends up with must match the reservation.

aws rds restore-db-instance-from-db-snapshot \
    --db-instance-identifier my-restored-instance \
    --db-snapshot-identifier my-snapshot \
    --db-instance-class db.r7g.large \
    --availability-zone us-east-1a \
    --db-capacity-reservation-identifier my-reservation

Point-in-time restores take the same parameter:

aws rds restore-db-instance-to-point-in-time \
    --source-db-instance-identifier my-source-instance \
    --target-db-instance-identifier my-restored-instance \
    --use-latest-restorable-time \
    --db-instance-class db.r7g.large \
    --availability-zone us-east-1a \
    --db-capacity-reservation-identifier my-reservation

The restore-db-instance-from-s3 command accepts the parameter as well.

To move an existing DB instance into a reservation, specify the reservation in a modify request that also changes the DB instance class, the Multi-AZ setting, or the license model, or that converts an RDS for Oracle DB instance from the non-CDB architecture to the CDB architecture. For a CDB conversion, the reservation engine must be oracle-ee-cdb or oracle-se2-cdb. The reservation must match the configuration that the DB instance has after the change. For example, to scale a DB instance to db.r7g.large and place it in a db.r7g.large reservation:

aws rds modify-db-instance \
    --db-instance-identifier my-db-instance \
    --db-instance-class db.r7g.large \
    --db-capacity-reservation-identifier my-reservation \
    --apply-immediately

A modify request that specifies a reservation without one of these changes fails. To move a DB instance into a reservation without changing its configuration, stop the DB instance, and then start it with the reservation. For more information, see Stopping and starting a DB instance in a reservation.

When DB instances are placed into the reservation, the AvailableCapacity for the affected Availability Zone decreases. You can track this with describe-db-capacity-reservations.

RDS API

Specify the DBCapacityReservationIdentifier parameter in the CreateDBInstance, CreateDBInstanceReadReplica, RestoreDBInstanceFromDBSnapshot, RestoreDBInstanceToPointInTime, RestoreDBInstanceFromS3, ModifyDBInstance, or StartDBInstance operation.