create_db_capacity_reservation¶
Operation¶
create_db_capacity_reservation
async
¶
create_db_capacity_reservation(request: CreateDBCapacityReservationInput | CreateDBCapacityReservationInputDict, /, *, plugins: list[Plugin] | None = None) -> CreateDBCapacityReservationOutput
create_db_capacity_reservation(*, plugins: list[Plugin] | None = None, **kwargs: Unpack[CreateDBCapacityReservationInputDict]) -> CreateDBCapacityReservationOutput
Creates a DB capacity reservation. A DB capacity reservation reserves compute and memory capacity for DB instances of one DB instance class and one database engine. Amazon RDS reserves that capacity in each Availability Zone that you specify.
Amazon RDS reserves the same amount of capacity in every Availability
Zone in the request. You set that amount with
CapacityPerAvailabilityZone, and you set the Availability Zones with
AvailabilityZones. The total reserved capacity is
CapacityPerAvailabilityZone multiplied by the number of Availability
Zones.
Specify StartDate and CommitmentDuration together to create a
future-dated reservation. A future-dated reservation reserves capacity
for a period that starts later. Amazon RDS holds that capacity for the
length of the commitment.
A future-dated reservation has the following additional constraints:
-
DBInstanceClassmust be adb.c,db.m,db.r,db.t, ordb.xDB instance class. The letter afterdb.gives the DB instance class family. For example,db.x2g.xlargequalifies, anddb.z1d.xlargedoesn't. -
If
DBInstanceClassis adb.mordb.rDB instance class, it must be from generation 7 or later. The digit after the family letter gives the generation. For example,db.m7g.xlargequalifies, anddb.m5.xlargedoesn't. Adb.c,db.t, ordb.xDB instance class has no generation requirement. -
The reserved capacity must total at least 32 vCPUs in each Availability Zone. Multiply
CapacityPerAvailabilityZoneby the number of vCPUs of the DB instance class. The product must be 32 or more. -
CommitmentDurationmust be at least 14 days. For adb.xDB instance class, it must be at least 84 days. -
StartDatemust be from 5 to 120 days in the future.
Therefore, a DB instance class with 2 vCPUs needs a
CapacityPerAvailabilityZone of 16 or more, a class with 4 vCPUs needs
8 or more, a class with 8 vCPUs needs 4 or more, and a class with 16
vCPUs needs 2 or more. For the number of vCPUs of each DB instance
class, see DB instance
classes
in the Amazon RDS User Guide.
Note
You can't modify a future-dated reservation before it starts. You
can't cancel a future-dated reservation in the scheduled state. You
can't cancel a reservation in the active state during its capacity
commitment. Therefore, you can't cancel a future-dated reservation from
the time that Amazon RDS schedules it until the commitment ends.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
plugins
|
list[Plugin] | None
|
A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations. |
None
|
Returns:
| Type | Description |
|---|---|
CreateDBCapacityReservationOutput
|
An instance of |
Input¶
Pass the input fields as keyword arguments, or pass a model or dictionary as the first positional argument. Pass plugins separately as a keyword argument.
Model¶
CreateDBCapacityReservationInput
dataclass
¶
Bases: _SerdeShape
Dataclass for CreateDBCapacityReservationInput structure.
Attributes¶
availability_zones
class-attribute
instance-attribute
¶
A list of Availability Zones for the reservation.
You can't change the Availability Zones of a reservation after you create it. Reserved capacity in an Availability Zone that no DB instance uses stays unused.
Constraints:
-
Must specify one or more Availability Zones.
-
Each Availability Zone can appear only once.
-
Each Availability Zone must be in the Amazon Web Services Region of the request.
-
Each Availability Zone must have capacity for the requested DB instance class.
-
Must include two or more Availability Zones to use the reservation for a Multi-AZ DB instance.
-
A DB instance can use reserved capacity only in an Availability Zone that its DB subnet group covers.
Example: us-east-1a
capacity_per_availability_zone
class-attribute
instance-attribute
¶
capacity_per_availability_zone: int | None = ...
The number of DB instances to reserve in each Availability Zone that you
list in AvailabilityZones. Amazon RDS reserves this number of DB
instances in every listed Availability Zone.
A Single-AZ DB instance uses one unit of reserved capacity, in one Availability Zone. A Multi-AZ DB instance is one DB instance, and it uses one unit of reserved capacity in each of two Availability Zones. Therefore, a Multi-AZ DB instance uses two units in total. A read replica uses one unit of reserved capacity, in the same way as any other DB instance.
Amazon RDS reserves capacity in each Availability Zone separately. Reserved capacity in one Availability Zone can't serve a DB instance in another Availability Zone. A request for a DB instance fails when the Availability Zone of the DB instance has no available capacity.
Therefore, set this value to the number of DB instances that you want to run at the same time in one Availability Zone. Don't set it to the number that you want in total.
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. Your existing DB instances, and the unused capacity of your other reservations, count against the same quota.
To find the value of the DB instances quota, see Quotas and constraints for Amazon RDS in the Amazon RDS User Guide.
Constraints:
- Minimum 1.
commitment_duration
class-attribute
instance-attribute
¶
commitment_duration: int | None = ...
The length of the capacity commitment that you request for a
future-dated reservation, in seconds. Amazon RDS measures this length
from StartDate.
Note
Amazon RDS can grant a shorter capacity commitment than you request.
Therefore, read CommitmentEndDate in CommitmentInfo for the
commitment that Amazon RDS granted.
The commitment doesn't end the reservation. Specify EndDate to set an
expiration date. You can't cancel a reservation in the active state
during the commitment.
Constraints:
-
Minimum 1209600, which is 14 days. For a
db.xDB instance class, such asdb.x2g.xlarge, the minimum is 7257600, which is 84 days. -
Must be less than 315576000, which is 10 years.
-
You must also specify
StartDate.
Example: 2592000
db_capacity_reservation_name
class-attribute
instance-attribute
¶
db_capacity_reservation_name: str | None = ...
The name of the DB capacity reservation. This name must be unique for your Amazon Web Services account in the Amazon Web Services Region.
Constraints:
-
Must contain from 1 to 63 lowercase letters, digits, or hyphens.
-
First character must be a lowercase letter.
-
Can't end with a hyphen or contain two consecutive hyphens.
-
Can't contain more than 16 groups of characters separated by hyphens.
-
Can't begin with
dbcr-.
db_instance_class
class-attribute
instance-attribute
¶
db_instance_class: str | None = ...
The compute and memory capacity to reserve, for example db.m5.large.
Not all DB instance classes are available in all Amazon Web Services
Regions, or for all database engines. For the full list of DB instance
classes, and availability for your engine, see DB instance
classes
in the Amazon RDS User Guide.
Constraints:
-
Must be a DB instance class that the specified
Enginesupports. -
For RDS for Oracle with
LicenseModelset tolicense-included, some DB instance classes aren't supported. Either choose a supported DB instance class, or setLicenseModeltobring-your-own-license.
end_date
class-attribute
instance-attribute
¶
end_date: datetime | None = ...
The date and time when the reservation expires, in Universal Coordinated Time (UTC). If you don't specify a value, the reservation doesn't expire.
To change the expiration of an existing reservation, use
ModifyDBCapacityReservation. That operation takes EndDateType along
with EndDate.
Constraints:
-
Must be a date and time in the future.
-
For a future-dated reservation, must be at or after
StartDateplusCommitmentDuration. For example, a reservation that starts on 2026-12-01 with a 30-day commitment can't expire before 2026-12-31. To reserve capacity for one calendar month, setCommitmentDurationto 30 days or fewer, not to the length of the month.
Example: 2026-12-31T23:59:59Z
engine
class-attribute
instance-attribute
¶
engine: str | None = ...
The database engine to reserve capacity for.
Valid Values: aurora-mysql | aurora-postgresql | mysql |
postgres | mariadb | oracle-ee | oracle-ee-cdb |
oracle-se2 | oracle-se2-cdb | sqlserver-ee | sqlserver-se |
sqlserver-web | sqlserver-ex | sqlserver-dev-ee |
sqlserver-dev-se | db2-ae | db2-ce | db2-se
Note
The Developer Edition engines sqlserver-dev-ee and sqlserver-dev-se
support no Multi-AZ DB instance and no read replica. Therefore, a
reservation for either engine serves Single-AZ DB instances only.
license_model
class-attribute
instance-attribute
¶
license_model: str | None = ...
The license model to reserve capacity for. Specify this parameter only for RDS for Microsoft SQL Server Enterprise Edition, Standard Edition, and Developer Edition, for RDS for Oracle, or for RDS for Db2 Standard Edition and Advanced Edition. Amazon RDS rejects the request for any other engine. This includes Amazon Aurora, the Web and Express editions of RDS for Microsoft SQL Server, and RDS for Db2 Community Edition.
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
A DB instance launches into the reservation only when the license model of the DB instance matches the license model of the reservation. For a reservation that holds no license model, Amazon RDS applies no license model check at launch.
For RDS for Microsoft SQL Server Enterprise Edition and Standard
Edition, if you don't specify a value, Amazon RDS uses
license-included.
For RDS for Microsoft SQL Server Developer Edition, if you don't
specify a value, Amazon RDS uses bring-your-own-license. That is the
only license model that these engines accept, and Amazon RDS rejects any
other value.
For RDS for Oracle, if you don't specify a value, Amazon RDS uses the only orderable license model for the DB instance class. If more than one license model is orderable, you must specify one.
For RDS for Db2 Standard Edition and Advanced Edition, if you don't
specify a value, Amazon RDS uses bring-your-own-license. To reserve
capacity for Db2 DB instances that you license through Amazon Web
Services Marketplace, specify marketplace-license.
Note
For RDS for Oracle, the license models that you can reserve depend on
the engine and the DB instance class. RDS for Oracle Enterprise Edition
doesn't support license-included.
start_date
class-attribute
instance-attribute
¶
start_date: datetime | None = ...
The date and time when the reservation starts, in Universal Coordinated Time (UTC). Specify this parameter to create a future-dated reservation. If you don't specify a value, the reservation starts immediately.
A reservation that starts later always carries a capacity commitment.
Therefore, a request that specifies StartDate must also meet every
constraint of a future-dated reservation, including the minimum reserved
capacity in each Availability Zone.
Constraints:
-
Must be from 5 to 120 days in the future.
-
You must also specify
CommitmentDuration.
Example: 2026-12-01T00:00:00Z
Dictionaries¶
CreateDBCapacityReservationInputDict
¶
Bases: TypedDict
Dictionary form of CreateDBCapacityReservationInput.
Attributes¶
availability_zones
instance-attribute
¶
A list of Availability Zones for the reservation.
You can't change the Availability Zones of a reservation after you create it. Reserved capacity in an Availability Zone that no DB instance uses stays unused.
Constraints:
-
Must specify one or more Availability Zones.
-
Each Availability Zone can appear only once.
-
Each Availability Zone must be in the Amazon Web Services Region of the request.
-
Each Availability Zone must have capacity for the requested DB instance class.
-
Must include two or more Availability Zones to use the reservation for a Multi-AZ DB instance.
-
A DB instance can use reserved capacity only in an Availability Zone that its DB subnet group covers.
Example: us-east-1a
capacity_per_availability_zone
instance-attribute
¶
The number of DB instances to reserve in each Availability Zone that you
list in AvailabilityZones. Amazon RDS reserves this number of DB
instances in every listed Availability Zone.
A Single-AZ DB instance uses one unit of reserved capacity, in one Availability Zone. A Multi-AZ DB instance is one DB instance, and it uses one unit of reserved capacity in each of two Availability Zones. Therefore, a Multi-AZ DB instance uses two units in total. A read replica uses one unit of reserved capacity, in the same way as any other DB instance.
Amazon RDS reserves capacity in each Availability Zone separately. Reserved capacity in one Availability Zone can't serve a DB instance in another Availability Zone. A request for a DB instance fails when the Availability Zone of the DB instance has no available capacity.
Therefore, set this value to the number of DB instances that you want to run at the same time in one Availability Zone. Don't set it to the number that you want in total.
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. Your existing DB instances, and the unused capacity of your other reservations, count against the same quota.
To find the value of the DB instances quota, see Quotas and constraints for Amazon RDS in the Amazon RDS User Guide.
Constraints:
- Minimum 1.
commitment_duration
instance-attribute
¶
commitment_duration: int | None
The length of the capacity commitment that you request for a
future-dated reservation, in seconds. Amazon RDS measures this length
from StartDate.
Note
Amazon RDS can grant a shorter capacity commitment than you request.
Therefore, read CommitmentEndDate in CommitmentInfo for the
commitment that Amazon RDS granted.
The commitment doesn't end the reservation. Specify EndDate to set an
expiration date. You can't cancel a reservation in the active state
during the commitment.
Constraints:
-
Minimum 1209600, which is 14 days. For a
db.xDB instance class, such asdb.x2g.xlarge, the minimum is 7257600, which is 84 days. -
Must be less than 315576000, which is 10 years.
-
You must also specify
StartDate.
Example: 2592000
db_capacity_reservation_name
instance-attribute
¶
The name of the DB capacity reservation. This name must be unique for your Amazon Web Services account in the Amazon Web Services Region.
Constraints:
-
Must contain from 1 to 63 lowercase letters, digits, or hyphens.
-
First character must be a lowercase letter.
-
Can't end with a hyphen or contain two consecutive hyphens.
-
Can't contain more than 16 groups of characters separated by hyphens.
-
Can't begin with
dbcr-.
db_instance_class
instance-attribute
¶
The compute and memory capacity to reserve, for example db.m5.large.
Not all DB instance classes are available in all Amazon Web Services
Regions, or for all database engines. For the full list of DB instance
classes, and availability for your engine, see DB instance
classes
in the Amazon RDS User Guide.
Constraints:
-
Must be a DB instance class that the specified
Enginesupports. -
For RDS for Oracle with
LicenseModelset tolicense-included, some DB instance classes aren't supported. Either choose a supported DB instance class, or setLicenseModeltobring-your-own-license.
end_date
instance-attribute
¶
end_date: datetime | None
The date and time when the reservation expires, in Universal Coordinated Time (UTC). If you don't specify a value, the reservation doesn't expire.
To change the expiration of an existing reservation, use
ModifyDBCapacityReservation. That operation takes EndDateType along
with EndDate.
Constraints:
-
Must be a date and time in the future.
-
For a future-dated reservation, must be at or after
StartDateplusCommitmentDuration. For example, a reservation that starts on 2026-12-01 with a 30-day commitment can't expire before 2026-12-31. To reserve capacity for one calendar month, setCommitmentDurationto 30 days or fewer, not to the length of the month.
Example: 2026-12-31T23:59:59Z
engine
instance-attribute
¶
The database engine to reserve capacity for.
Valid Values: aurora-mysql | aurora-postgresql | mysql |
postgres | mariadb | oracle-ee | oracle-ee-cdb |
oracle-se2 | oracle-se2-cdb | sqlserver-ee | sqlserver-se |
sqlserver-web | sqlserver-ex | sqlserver-dev-ee |
sqlserver-dev-se | db2-ae | db2-ce | db2-se
Note
The Developer Edition engines sqlserver-dev-ee and sqlserver-dev-se
support no Multi-AZ DB instance and no read replica. Therefore, a
reservation for either engine serves Single-AZ DB instances only.
license_model
instance-attribute
¶
license_model: str | None
The license model to reserve capacity for. Specify this parameter only for RDS for Microsoft SQL Server Enterprise Edition, Standard Edition, and Developer Edition, for RDS for Oracle, or for RDS for Db2 Standard Edition and Advanced Edition. Amazon RDS rejects the request for any other engine. This includes Amazon Aurora, the Web and Express editions of RDS for Microsoft SQL Server, and RDS for Db2 Community Edition.
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
A DB instance launches into the reservation only when the license model of the DB instance matches the license model of the reservation. For a reservation that holds no license model, Amazon RDS applies no license model check at launch.
For RDS for Microsoft SQL Server Enterprise Edition and Standard
Edition, if you don't specify a value, Amazon RDS uses
license-included.
For RDS for Microsoft SQL Server Developer Edition, if you don't
specify a value, Amazon RDS uses bring-your-own-license. That is the
only license model that these engines accept, and Amazon RDS rejects any
other value.
For RDS for Oracle, if you don't specify a value, Amazon RDS uses the only orderable license model for the DB instance class. If more than one license model is orderable, you must specify one.
For RDS for Db2 Standard Edition and Advanced Edition, if you don't
specify a value, Amazon RDS uses bring-your-own-license. To reserve
capacity for Db2 DB instances that you license through Amazon Web
Services Marketplace, specify marketplace-license.
Note
For RDS for Oracle, the license models that you can reserve depend on
the engine and the DB instance class. RDS for Oracle Enterprise Edition
doesn't support license-included.
start_date
instance-attribute
¶
start_date: datetime | None
The date and time when the reservation starts, in Universal Coordinated Time (UTC). Specify this parameter to create a future-dated reservation. If you don't specify a value, the reservation starts immediately.
A reservation that starts later always carries a capacity commitment.
Therefore, a request that specifies StartDate must also meet every
constraint of a future-dated reservation, including the minimum reserved
capacity in each Availability Zone.
Constraints:
-
Must be from 5 to 120 days in the future.
-
You must also specify
CommitmentDuration.
Example: 2026-12-01T00:00:00Z
Output¶
CreateDBCapacityReservationOutput
dataclass
¶
Bases: _SerdeShape
Dataclass for CreateDBCapacityReservationOutput structure.
Attributes¶
db_capacity_reservation
class-attribute
instance-attribute
¶
db_capacity_reservation: DBCapacityReservation | None = ...
Contains the details of the newly created DB capacity reservation.
response_metadata
class-attribute
instance-attribute
¶
Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.