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 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 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:


And here is an example response:


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

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


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 expiration settings.


DynamoDB does not remove expired items immediately. See How It Works: DynamoDB Time to Live 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 convenient 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.

You just need a table with a single partition key. A value attribute (containing response data) will be created dynamically once items are added to the table.

  • Table: http_cache (or any other name, as long as it matches the table_name parameter for DynamoDbCache)

  • Attributes:

    • key: String

  • Keys:

    • Partition key (aka hash key): key

Example of manually creating a table in the console:


Example CloudFormation Template#



AWSTemplateFormatVersion: '2010-09-09'
Description: An example of creating a DynamoDB table to use as a requests-cache backend

    Type: String
    Default: http_cache
    Description: >
      An alternate DynamoDB table name to use. If provided, this must match the
      table_name parameter for DynamoDbCache.

    Type: AWS::DynamoDB::Table
      TableName: !Ref CacheTableName
        - AttributeName: key
          AttributeType: S
        - AttributeName: key
          KeyType: HASH
      # BillingMode: PAY_PER_REQUEST

      # Optional: Use provisioned throughput instead of on-demand
      BillingMode: PROVISIONED
        WriteCapacityUnits: 2
        ReadCapacityUnits: 2

      # Optional: Enable DynamoDB's TTL feature
        AttributeName: ttl
        Enabled: true

To deploy with the AWS CLI:

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