# Amazon DynamoDB Construct Library
<!--BEGIN STABILITY BANNER-->---
---
<!--END STABILITY BANNER-->
Here is a minimal deployable DynamoDB table definition:
```python
table = dynamodb.Table(self, "Table",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING)
)
```
## Importing existing tables
To import an existing table into your CDK application, use the `Table.fromTableName`, `Table.fromTableArn` or `Table.fromTableAttributes`
factory method. This method accepts table name or table ARN which describes the properties of an already
existing table:
```python
# user: iam.User
table = dynamodb.Table.from_table_arn(self, "ImportedTable", "arn:aws:dynamodb:us-east-1:111111111:table/my-table")
# now you can just call methods on the table
table.grant_read_write_data(user)
```
If you intend to use the `tableStreamArn` (including indirectly, for example by creating an
`@aws-cdk/aws-lambda-event-source.DynamoEventSource` on the imported table), you *must* use the
`Table.fromTableAttributes` method and the `tableStreamArn` property *must* be populated.
## Keys
When a table is defined, you must define it's schema using the `partitionKey`
(required) and `sortKey` (optional) properties.
## Billing Mode
DynamoDB supports two billing modes:
* PROVISIONED - the default mode where the table and global secondary indexes have configured read and write capacity.
* PAY_PER_REQUEST - on-demand pricing and scaling. You only pay for what you use and there is no read and write capacity for the table or its global secondary indexes.
```python
table = dynamodb.Table(self, "Table",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST
)
```
Further reading:
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.
## Table Class
DynamoDB supports two table classes:
* STANDARD - the default mode, and is recommended for the vast majority of workloads.
* STANDARD_INFREQUENT_ACCESS - optimized for tables where storage is the dominant cost.
```python
table = dynamodb.Table(self, "Table",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
table_class=dynamodb.TableClass.STANDARD_INFREQUENT_ACCESS
)
```
Further reading:
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.TableClasses.html
## Configure AutoScaling for your table
You can have DynamoDB automatically raise and lower the read and write capacities
of your table by setting up autoscaling. You can use this to either keep your
tables at a desired utilization level, or by scaling up and down at pre-configured
times of the day:
Auto-scaling is only relevant for tables with the billing mode, PROVISIONED.
```python
read_scaling = table.auto_scale_read_capacity(min_capacity=1, max_capacity=50)
read_scaling.scale_on_utilization(
target_utilization_percent=50
)
read_scaling.scale_on_schedule("ScaleUpInTheMorning",
schedule=appscaling.Schedule.cron(hour="8", minute="0"),
min_capacity=20
)
read_scaling.scale_on_schedule("ScaleDownAtNight",
schedule=appscaling.Schedule.cron(hour="20", minute="0"),
max_capacity=20
)
```
Further reading:
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AutoScaling.html
https://aws.amazon.com/blogs/database/how-to-use-aws-cloudformation-to-configure-auto-scaling-for-amazon-dynamodb-tables-and-indexes/
## Amazon DynamoDB Global Tables
You can create DynamoDB Global Tables by setting the `replicationRegions` property on a `Table`:
```python
global_table = dynamodb.Table(self, "Table",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
replication_regions=["us-east-1", "us-east-2", "us-west-2"]
)
```
When doing so, a CloudFormation Custom Resource will be added to the stack in order to create the replica tables in the
selected regions.
The default billing mode for Global Tables is `PAY_PER_REQUEST`.
If you want to use `PROVISIONED`,
you have to make sure write auto-scaling is enabled for that Table:
```python
global_table = dynamodb.Table(self, "Table",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
replication_regions=["us-east-1", "us-east-2", "us-west-2"],
billing_mode=dynamodb.BillingMode.PROVISIONED
)
global_table.auto_scale_write_capacity(
min_capacity=1,
max_capacity=10
).scale_on_utilization(target_utilization_percent=75)
```
When adding a replica region for a large table, you might want to increase the
timeout for the replication operation:
```python
global_table = dynamodb.Table(self, "Table",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
replication_regions=["us-east-1", "us-east-2", "us-west-2"],
replication_timeout=Duration.hours(2)
)
```
## Encryption
All user data stored in Amazon DynamoDB is fully encrypted at rest. When creating a new table, you can choose to encrypt using the following customer master keys (CMK) to encrypt your table:
* AWS owned CMK - By default, all tables are encrypted under an AWS owned customer master key (CMK) in the DynamoDB service account (no additional charges apply).
* AWS managed CMK - AWS KMS keys (one per region) are created in your account, managed, and used on your behalf by AWS DynamoDB (AWS KMS charges apply).
* Customer managed CMK - You have full control over the KMS key used to encrypt the DynamoDB Table (AWS KMS charges apply).
Creating a Table encrypted with a customer managed CMK:
```python
table = dynamodb.Table(self, "MyTable",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
encryption=dynamodb.TableEncryption.CUSTOMER_MANAGED
)
# You can access the CMK that was added to the stack on your behalf by the Table construct via:
table_encryption_key = table.encryption_key
```
You can also supply your own key:
```python
import aws_cdk.aws_kms as kms
encryption_key = kms.Key(self, "Key",
enable_key_rotation=True
)
table = dynamodb.Table(self, "MyTable",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
encryption=dynamodb.TableEncryption.CUSTOMER_MANAGED,
encryption_key=encryption_key
)
```
In order to use the AWS managed CMK instead, change the code to:
```python
table = dynamodb.Table(self, "MyTable",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
encryption=dynamodb.TableEncryption.AWS_MANAGED
)
```
## Get schema of table or secondary indexes
To get the partition key and sort key of the table or indexes you have configured:
```python
# table: dynamodb.Table
schema = table.schema()
partition_key = schema.partition_key
sort_key = schema.sort_key
```
## Kinesis Stream
A Kinesis Data Stream can be configured on the DynamoDB table to capture item-level changes.
```python
import aws_cdk.aws_kinesis as kinesis
stream = kinesis.Stream(self, "Stream")
table = dynamodb.Table(self, "Table",
partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
kinesis_stream=stream
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-dynamodb",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/55/37/a417504eecf43539c1ac54b2945a5e70cf36b7f0d52704836219343be8fd/aws-cdk.aws-dynamodb-1.203.0.tar.gz",
"platform": null,
"description": "# Amazon DynamoDB Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n\n\n---\n<!--END STABILITY BANNER-->\n\nHere is a minimal deployable DynamoDB table definition:\n\n```python\ntable = dynamodb.Table(self, \"Table\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING)\n)\n```\n\n## Importing existing tables\n\nTo import an existing table into your CDK application, use the `Table.fromTableName`, `Table.fromTableArn` or `Table.fromTableAttributes`\nfactory method. This method accepts table name or table ARN which describes the properties of an already\nexisting table:\n\n```python\n# user: iam.User\n\ntable = dynamodb.Table.from_table_arn(self, \"ImportedTable\", \"arn:aws:dynamodb:us-east-1:111111111:table/my-table\")\n# now you can just call methods on the table\ntable.grant_read_write_data(user)\n```\n\nIf you intend to use the `tableStreamArn` (including indirectly, for example by creating an\n`@aws-cdk/aws-lambda-event-source.DynamoEventSource` on the imported table), you *must* use the\n`Table.fromTableAttributes` method and the `tableStreamArn` property *must* be populated.\n\n## Keys\n\nWhen a table is defined, you must define it's schema using the `partitionKey`\n(required) and `sortKey` (optional) properties.\n\n## Billing Mode\n\nDynamoDB supports two billing modes:\n\n* PROVISIONED - the default mode where the table and global secondary indexes have configured read and write capacity.\n* PAY_PER_REQUEST - on-demand pricing and scaling. You only pay for what you use and there is no read and write capacity for the table or its global secondary indexes.\n\n```python\ntable = dynamodb.Table(self, \"Table\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST\n)\n```\n\nFurther reading:\nhttps://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.\n\n## Table Class\n\nDynamoDB supports two table classes:\n\n* STANDARD - the default mode, and is recommended for the vast majority of workloads.\n* STANDARD_INFREQUENT_ACCESS - optimized for tables where storage is the dominant cost.\n\n```python\ntable = dynamodb.Table(self, \"Table\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n table_class=dynamodb.TableClass.STANDARD_INFREQUENT_ACCESS\n)\n```\n\nFurther reading:\nhttps://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.TableClasses.html\n\n## Configure AutoScaling for your table\n\nYou can have DynamoDB automatically raise and lower the read and write capacities\nof your table by setting up autoscaling. You can use this to either keep your\ntables at a desired utilization level, or by scaling up and down at pre-configured\ntimes of the day:\n\nAuto-scaling is only relevant for tables with the billing mode, PROVISIONED.\n\n```python\nread_scaling = table.auto_scale_read_capacity(min_capacity=1, max_capacity=50)\n\nread_scaling.scale_on_utilization(\n target_utilization_percent=50\n)\n\nread_scaling.scale_on_schedule(\"ScaleUpInTheMorning\",\n schedule=appscaling.Schedule.cron(hour=\"8\", minute=\"0\"),\n min_capacity=20\n)\n\nread_scaling.scale_on_schedule(\"ScaleDownAtNight\",\n schedule=appscaling.Schedule.cron(hour=\"20\", minute=\"0\"),\n max_capacity=20\n)\n```\n\nFurther reading:\nhttps://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AutoScaling.html\nhttps://aws.amazon.com/blogs/database/how-to-use-aws-cloudformation-to-configure-auto-scaling-for-amazon-dynamodb-tables-and-indexes/\n\n## Amazon DynamoDB Global Tables\n\nYou can create DynamoDB Global Tables by setting the `replicationRegions` property on a `Table`:\n\n```python\nglobal_table = dynamodb.Table(self, \"Table\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n replication_regions=[\"us-east-1\", \"us-east-2\", \"us-west-2\"]\n)\n```\n\nWhen doing so, a CloudFormation Custom Resource will be added to the stack in order to create the replica tables in the\nselected regions.\n\nThe default billing mode for Global Tables is `PAY_PER_REQUEST`.\nIf you want to use `PROVISIONED`,\nyou have to make sure write auto-scaling is enabled for that Table:\n\n```python\nglobal_table = dynamodb.Table(self, \"Table\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n replication_regions=[\"us-east-1\", \"us-east-2\", \"us-west-2\"],\n billing_mode=dynamodb.BillingMode.PROVISIONED\n)\n\nglobal_table.auto_scale_write_capacity(\n min_capacity=1,\n max_capacity=10\n).scale_on_utilization(target_utilization_percent=75)\n```\n\nWhen adding a replica region for a large table, you might want to increase the\ntimeout for the replication operation:\n\n```python\nglobal_table = dynamodb.Table(self, \"Table\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n replication_regions=[\"us-east-1\", \"us-east-2\", \"us-west-2\"],\n replication_timeout=Duration.hours(2)\n)\n```\n\n## Encryption\n\nAll user data stored in Amazon DynamoDB is fully encrypted at rest. When creating a new table, you can choose to encrypt using the following customer master keys (CMK) to encrypt your table:\n\n* AWS owned CMK - By default, all tables are encrypted under an AWS owned customer master key (CMK) in the DynamoDB service account (no additional charges apply).\n* AWS managed CMK - AWS KMS keys (one per region) are created in your account, managed, and used on your behalf by AWS DynamoDB (AWS KMS charges apply).\n* Customer managed CMK - You have full control over the KMS key used to encrypt the DynamoDB Table (AWS KMS charges apply).\n\nCreating a Table encrypted with a customer managed CMK:\n\n```python\ntable = dynamodb.Table(self, \"MyTable\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n encryption=dynamodb.TableEncryption.CUSTOMER_MANAGED\n)\n\n# You can access the CMK that was added to the stack on your behalf by the Table construct via:\ntable_encryption_key = table.encryption_key\n```\n\nYou can also supply your own key:\n\n```python\nimport aws_cdk.aws_kms as kms\n\n\nencryption_key = kms.Key(self, \"Key\",\n enable_key_rotation=True\n)\ntable = dynamodb.Table(self, \"MyTable\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n encryption=dynamodb.TableEncryption.CUSTOMER_MANAGED,\n encryption_key=encryption_key\n)\n```\n\nIn order to use the AWS managed CMK instead, change the code to:\n\n```python\ntable = dynamodb.Table(self, \"MyTable\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n encryption=dynamodb.TableEncryption.AWS_MANAGED\n)\n```\n\n## Get schema of table or secondary indexes\n\nTo get the partition key and sort key of the table or indexes you have configured:\n\n```python\n# table: dynamodb.Table\n\nschema = table.schema()\npartition_key = schema.partition_key\nsort_key = schema.sort_key\n```\n\n## Kinesis Stream\n\nA Kinesis Data Stream can be configured on the DynamoDB table to capture item-level changes.\n\n```python\nimport aws_cdk.aws_kinesis as kinesis\n\n\nstream = kinesis.Stream(self, \"Stream\")\n\ntable = dynamodb.Table(self, \"Table\",\n partition_key=dynamodb.Attribute(name=\"id\", type=dynamodb.AttributeType.STRING),\n kinesis_stream=stream\n)\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::DynamoDB",
"version": "1.203.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8165f683895529dcae6d67155bb6ea825bba8a1c105bd0672d69016e416e4e65",
"md5": "60ceb92248aae35accc7cfd081e1aa67",
"sha256": "846393548832140911e1520e06fca5432ab7f3979dd07739a563b76b1c1abaeb"
},
"downloads": -1,
"filename": "aws_cdk.aws_dynamodb-1.203.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60ceb92248aae35accc7cfd081e1aa67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 313662,
"upload_time": "2023-05-31T22:54:24",
"upload_time_iso_8601": "2023-05-31T22:54:24.787874Z",
"url": "https://files.pythonhosted.org/packages/81/65/f683895529dcae6d67155bb6ea825bba8a1c105bd0672d69016e416e4e65/aws_cdk.aws_dynamodb-1.203.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5537a417504eecf43539c1ac54b2945a5e70cf36b7f0d52704836219343be8fd",
"md5": "84f59424b3a0afa655b3e7aeecdc4019",
"sha256": "d90a935374e3411dd7faee7102f04fc14868950439d58f79493e1dd3b14f9beb"
},
"downloads": -1,
"filename": "aws-cdk.aws-dynamodb-1.203.0.tar.gz",
"has_sig": false,
"md5_digest": "84f59424b3a0afa655b3e7aeecdc4019",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 313961,
"upload_time": "2023-05-31T23:01:59",
"upload_time_iso_8601": "2023-05-31T23:01:59.066347Z",
"url": "https://files.pythonhosted.org/packages/55/37/a417504eecf43539c1ac54b2945a5e70cf36b7f0d52704836219343be8fd/aws-cdk.aws-dynamodb-1.203.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 23:01:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-dynamodb"
}
JSON
