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.

Warning

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:

Screenshot

And here is an example response:

Screenshot

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

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

Warning

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:

Screenshot

Example CloudFormation Template

Example

cloudformation.yml

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

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

Resources:
  DynamoDBRequestCache:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: !Ref CacheTableName
      AttributeDefinitions:
        - AttributeName: key
          AttributeType: S
      KeySchema:
        - AttributeName: key
          KeyType: HASH
      # BillingMode: PAY_PER_REQUEST

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

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

To deploy with the AWS CLI:

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