(dynamodb)=

DynamoDB

DynamoDB is a fully managed, highly scalable NoSQL document database hosted on Amazon Web Services.

Use Cases

In terms of features, DynamoDB is roughly comparable to MongoDB and other NoSQL databases. Since it‘s a managed service, no server setup or maintenance is required, and it’s very convenient to use if your application is already on AWS. It is an especially good fit for serverless applications running on AWS Lambda.

DynamoDB item sizes are limited to 400KB. If you need to cache larger responses, consider
using a different backend.

Usage Example

Initialize with a {py:class}.DynamoDbCache instance:

>>> from requests_cache import CachedSession, DynamoDbCache
>>> session = CachedSession(backend=DynamoDbCache())

Or by alias:

>>> session = CachedSession(backend='dynamodb')

Connection Options

This backend accepts any keyword arguments for {py:meth}boto3.session.Session.resource:

>>> backend = DynamoDbCache(region_name='us-west-2')
>>> session = CachedSession(backend=backend)

Viewing Responses

By default, responses are only partially serialized so they can be saved as plain DynamoDB documents. Response data can then be easily viewed via the AWS Console.

Here is an example of responses listed under DynamoDB > Tables > Explore Items: :::{admonition} Screenshot :class: toggle

:::

And here is an example response: :::{admonition} Screenshot :class: toggle

:::

It is also possible query these responses with the AWS CLI, for example:

aws dynamodb query \
    --table-name http_cache \
    --key-condition-expression "namespace = :n1" \
    --expression-attribute-values '{":n1": {"S": "responses"}}' \
    > responses.json

Expiration

DynamoDB natively supports TTL on a per-item basis, and can automatically remove expired responses from the cache. This will be set by by default, according to normal {ref}expiration settings <expiration>.

DynamoDB does not remove expired items immediately. See
[How It Works: DynamoDB Time to Live](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html)
for more details.

If needed, you can disable this behavior with the ttl argument:

>>> backend = DynamoDbCache(ttl=False)

Creating a Table

A table will be automatically created if one doesn't already exist. This is convienient if you just want to quickly test out DynamoDB as a cache backend, but in a production environment you will likely want to create the tables yourself, for example with CloudFormation or Terraform.

Here are the details you will need:

• Table: http_cache (or any other name, as long as it matches the table_name parameter for DynamoDbCache)
• Attributes:
  • namespace: String
  • key: String
• Keys:
  • Partition key (aka namespace): namespace
  • Range key (aka sort key): key

Example CloudFormation Template

:::{admonition} Example: cloudformation.yml :class: toggle

:language: yaml

:::

To deploy with the AWS CLI:

aws cloudformation deploy \
    --stack-name requests-cache \
    --template-file examples/cloudformation.yml