AWS CLI Command Reference

[ aws . rds ]

modify-db-capacity-reservation

Description

Modifies a DB capacity reservation. You can change the reserved capacity in each Availability Zone of the reservation, and you can change the end date of the reservation. You can’t change the Availability Zones of an existing reservation.

The reservation must be in the active state. A future-dated reservation that hasn’t started isn’t modifiable, and neither is a reservation that Amazon RDS is already modifying.

You must specify CapacityPerAvailabilityZone , EndDateType , or EndDate . A request that specifies none of the three changes nothing, and Amazon RDS rejects it.

See also: AWS API Documentation

Synopsis

  modify-db-capacity-reservation
--db-capacity-reservation-identifier <value>
[--capacity-per-availability-zone <value>]
[--end-date-type <value>]
[--end-date <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
[--cli-error-format <value>]

Options

--db-capacity-reservation-identifier (string) [required]

The identifier or the name of the DB capacity reservation to modify. You can specify the identifier, which has the prefix dbcr- , or the reservation name.

Constraints:

  • min: 1
  • max: 63
  • pattern: [a-z](?:-?[a-z0-9]+){0,15}

--capacity-per-availability-zone (integer)

The new number of DB instances to reserve in each Availability Zone of the reservation. Amazon RDS applies this number to every Availability Zone of the reservation.

An increase reserves more capacity at the time of the request, so it can fail when the Amazon Web Services Region has insufficient capacity.

This value multiplied by the number of Availability Zones counts against the DB instances quota for your Amazon Web Services account in the Amazon Web Services Region. Amazon RDS checks the quota only when you increase the value.

Constraints:

  • Minimum 1.
  • Can’t be less than the highest number of DB instances that use the reservation in any single Availability Zone of the reservation. That number includes a DB instance that holds a unit of reserved capacity for a pending modification. To find that number for an Availability Zone, subtract AvailableCapacity from ReservedCapacityPerAvailabilityZone .
  • During a capacity commitment, can’t be less than CommittedCapacityPerAvailabilityZone .

--end-date-type (string)

The end date type for the reservation.

Valid Values:

  • limited - The reservation has a specific end date. You must also specify EndDate .
  • unlimited - The reservation doesn’t expire. Don’t specify EndDate .

Possible values:

  • unlimited
  • limited

--end-date (timestamp)

The new end date for the reservation, in Universal Coordinated Time (UTC). Required when EndDateType is limited . Don’t specify a value when EndDateType is unlimited .

When you specify EndDate , you must also specify EndDateType .

Constraints:

  • Must be a date and time in the future.
  • During a capacity commitment, must be at or after CommitmentEndDate .

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

Global Options

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

  • json
  • text
  • table
  • yaml
  • yaml-stream
  • off

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

  • on
  • off
  • auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--cli-binary-format (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob fileb:// will always be treated as binary and use the file contents directly regardless of the cli-binary-format setting. When using file:// the file contents will need to properly formatted for the configured cli-binary-format.

  • base64
  • raw-in-base64-out

--no-cli-pager (boolean)

Disable cli pager for output.

--cli-auto-prompt (boolean)

Automatically prompt for CLI input parameters.

--no-cli-auto-prompt (boolean)

Disable automatically prompt for CLI input parameters.

--cli-error-format (string)

The formatting style for error output. By default, errors are displayed in enhanced format.

  • legacy
  • json
  • yaml
  • text
  • table
  • enhanced

Output

DBCapacityReservation -> (structure)

Contains the details of the modified DB capacity reservation.

DBCapacityReservationName -> (string)

The name that you specified for the DB capacity reservation.

Constraints:

  • min: 1
  • max: 63
  • pattern: [a-z](?:-?[a-z0-9]+){0,15}

DBInstanceClass -> (string)

The DB instance class for the reserved capacity. You specify this value when you create the reservation, and you can’t change it afterward.

Constraints:

  • min: 5
  • max: 30
  • pattern: db\.[0-9a-z]{2,6}\.[0-9a-z\.]{4,20}

Engine -> (string)

The database engine for the reserved capacity. You specify this value when you create the reservation, and you can’t change it afterward.

LicenseModel -> (string)

The license model for the reserved capacity. Amazon RDS returns this value only for a reservation that reserves capacity for a specific license model. Amazon RDS doesn’t return this value for a reservation whose database engine doesn’t support a license model.

A DB instance launches into the reservation only when the license model of the DB instance matches this value. For a reservation that holds no license model, Amazon RDS applies no license model check at launch.

Valid Values:

  • RDS for Microsoft SQL Server Enterprise Edition and Standard Edition - license-included | bring-your-own-media
  • RDS for Microsoft SQL Server Developer Edition - bring-your-own-license
  • RDS for Oracle - bring-your-own-license | license-included
  • RDS for Db2 Standard Edition and Advanced Edition - bring-your-own-license | marketplace-license

For RDS for Db2 Standard Edition and Advanced Edition, a reservation created without a license model holds bring-your-own-license .

ReservedCapacityPerAvailabilityZone -> (integer)

The number of DB instances that Amazon RDS reserves in each Availability Zone of the reservation. This value matches the CapacityPerAvailabilityZone parameter of the request. The total reserved capacity is this value multiplied by the number of Availability Zones of the reservation.

AvailableCapacityPerAvailabilityZoneList -> (list)

The unused capacity of the reservation, reported for each Availability Zone of the reservation. Each entry names one Availability Zone, and it reports the number of DB instances that remain available in that Availability Zone.

Amazon RDS reports available capacity only for a reservation that is in the active state and not past its end date. Otherwise, each entry reports an available capacity of 0 . A future-dated reservation that hasn’t started reports 0 , and a reservation that Amazon RDS is modifying reports 0 .

A reservation reports the pending state while Amazon RDS modifies it. Therefore, a reservation in the active state that reports no available capacity has no unused capacity.

(structure)

Contains the unused capacity of a DB capacity reservation in one Availability Zone.

This data type is used as a response element in the following operations:

  • CancelDBCapacityReservation
  • CreateDBCapacityReservation
  • DescribeDBCapacityReservations
  • ModifyDBCapacityReservation

AvailabilityZone -> (string)

The name of the Availability Zone.

AvailableCapacity -> (integer)

The number of DB instances that remain available in this Availability Zone. Amazon RDS decreases this value when a DB instance takes a unit of reserved capacity in this Availability Zone, and it increases this value when a DB instance releases that unit.

A DB instance with a pending modification also holds a unit of reserved capacity. A DB instance has a pending modification when Amazon RDS accepts a change to the DB instance and applies that change later, during the maintenance window. Amazon RDS holds the unit from the time that it accepts the request. To find a DB instance with a pending modification, check PendingModifiedValues in the response of DescribeDBInstances .

Amazon RDS reports available capacity only for a reservation that is in the active state and not past its end date. Otherwise, this value is 0 .

EndDate -> (timestamp)

The date and time when the reservation expires, in Universal Coordinated Time (UTC). Amazon RDS doesn’t return this value if the reservation doesn’t expire.

Warning

A DB instance that uses the reservation keeps running after the reservation expires. It continues on unreserved capacity, and Amazon RDS doesn’t stop it or modify it. However, Amazon RDS no longer reserves capacity for the DB instance. Amazon RDS might later move the DB instance to different hardware, for example during hardware maintenance. That move can fail when the Amazon Web Services Region has insufficient capacity for the DB instance class.

CreateDate -> (timestamp)

The date and time when the reservation was created, in Universal Coordinated Time (UTC).

StartDate -> (timestamp)

The date and time when a future-dated reservation starts, in Universal Coordinated Time (UTC). Amazon RDS doesn’t return this value for a reservation that started immediately.

CommitmentInfo -> (structure)

The capacity commitment of the reservation. Amazon RDS returns this object only for a future-dated reservation.

CommittedCapacityPerAvailabilityZone -> (integer)

The number of DB instances that Amazon RDS holds in each Availability Zone of the reservation for the length of the commitment.

CommitmentEndDate -> (timestamp)

The date and time when the commitment ends, in Universal Coordinated Time (UTC). This date reports the capacity commitment that Amazon RDS granted.

Amazon RDS can grant a shorter capacity commitment than you request in CommitmentDuration . Therefore, this date can fall earlier than StartDate plus CommitmentDuration .

State -> (string)

The current state of the DB capacity reservation. A DB instance can use the reservation in the active state only.

Valid Values:

  • active - Amazon RDS holds the reserved capacity, and a DB instance can use it.
  • pending - The reservation isn’t ready to use yet. Amazon RDS is creating the reserved capacity, or it is applying a requested modification.
  • assessing - Amazon RDS is evaluating the request for a future-dated reservation.
  • scheduled - Amazon RDS accepted a future-dated reservation, and the reservation is waiting for its start date.
  • delayed - Amazon RDS couldn’t provide the reserved capacity of a future-dated reservation by its start date.
  • unsupported - Amazon RDS can’t fulfill the future-dated reservation as requested.
  • expired - The reservation passed its end date. Amazon RDS releases the reserved capacity.
  • cancelled - You cancelled the reservation, and Amazon RDS released the reserved capacity.
  • failed - Amazon RDS couldn’t reserve the capacity.

The values assessing , scheduled , delayed , and unsupported apply to a future-dated reservation only.

Possible values:

  • active
  • expired
  • cancelled
  • pending
  • failed
  • assessing
  • scheduled
  • delayed
  • unsupported

DBCapacityReservationArn -> (string)

The Amazon Resource Name (ARN) of the DB capacity reservation.

DBCapacityReservationIdentifier -> (string)

The unique identifier of the DB capacity reservation. The identifier has the prefix dbcr- . Every other DB capacity reservation operation takes this identifier.

Constraints:

  • min: 1
  • max: 63
  • pattern: [a-z](?:-?[a-z0-9]+){0,15}

TagList -> (list)

The tags associated with the DB capacity reservation.

(structure)

Metadata assigned to an Amazon RDS resource consisting of a key-value pair.

For more information, see Tagging Amazon RDS resources in the Amazon RDS User Guide or Tagging Amazon Aurora and Amazon RDS resources in the Amazon Aurora User Guide .

Key -> (string)

A key is the required name of the tag. The string value can be from 1 to 128 Unicode characters in length and can’t be prefixed with aws: or rds: . The string can only contain only the set of Unicode letters, digits, white-space, ‘_’, ‘.’, ‘:’, ‘/’, ‘=’, ‘+’, ‘-’, ‘@’ (Java regex: “^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$”).

Value -> (string)

A value is the optional value of the tag. The string value can be from 1 to 256 Unicode characters in length and can’t be prefixed with aws: or rds: . The string can only contain only the set of Unicode letters, digits, white-space, ‘_’, ‘.’, ‘:’, ‘/’, ‘=’, ‘+’, ‘-’, ‘@’ (Java regex: “^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$”).
© Copyright 2026, Amazon Web Services. Created using Sphinx.