NAME

Starch::Store::Paws::DynamoDB - Starch storage backend using Paws::DynamoDB.

SYNOPSIS

my $starch = Starch->new(
    store => {
        class => '::Paws::DynamoDB',
        region => 'us-west-2',
    },
);

DESCRIPTION

This Starch store uses Paws::DynamoDB to set and get state data.

This module is meant to be a more robust replacement for Starch::Store::Amazon::DynamoDB for several reasons:

• Amazon::DynamoDB lacks many features and it does not appear like this will change any time soon.

• Paws appears to be the king of AWS API in Perl, likely deprecating many of the existing AWS modules on CPAN.

WARNING

Paws is not yet stable as it is being actively developed and no promises are being made in regards to API stability or quality of the software.

Thus, this module also does not make any such promises. Once Paws reaches version 1 this will change.

SERIALIZATION

Unlike Starch::Store::Amazon::DynamoDB this module does not jump through a bunch of hoops to serialize only complex data structures, nor does it give you the ability to choose a serializer.

Instead all data is serialized with JSON::MaybeXS. This makes things a lot simpler for tools written in other languages, or even just for humans looking at the raw records in DynamoDB. It also simplifies the code.

OPTIMIZATION

You should probably run the following code as early as possible:

use Paws;
Paws->default_config->immutable(1);

This will ensure that you get the most run-time performance, but with a small compile-time slow down. See more at "Optimization" in Paws.

This module automatically preloads the PutItem, GetItem, and DeleteItem methods of the Paws::DynamoDB class.

OPTIONAL ARGUMENTS

region

This is the AWS region which will be used when building the "paws" object. If you specify your own "paws" object (or aguments) then this will be ignored. Defaults to us-east-1.

ddb

This must be set to either hash ref arguments for Paws::DynamoDB or a pre-built object (often retrieved using a method proxy).

When configuring Starch from static configuration files using a method proxy is a good way to link your existing Paws::DynamoDB object constructor in with Starch so that starch doesn't build its own.

paws

The Paws object, which will be used to construct the "ddb" object.

If this is sepecified as a HashRef then a new Paws object will be created with the HashRef used as the config argumet.

See more at "CONFIGURATION" in Paws.

consistent_read

When true this sets the ConsistentRead flag when calling GetItem on the "ddb". Defaults to true.

table

The DynamoDB table name where states are stored. Defaults to starch_states.

key_field

The field in the "table" where the state ID is stored. Defaults to __STARCH_KEY__.

expiration_field

The field in the "table" which will hold the epoch time when the state should be expired. Defaults to __STARCH_EXPIRATION__.

connect_on_create

By default when this store is first created it will issue an "get". This initializes all the LWP and other code so that, in a forked environment (such as a web server) this initialization only happens once, not on every child's first request.

Defaults to 1 (true). Set this to false if you don't want this feature.

METHODS

create_table_args

Returns the appropriate arguments to use for calling CreateTable on the "ddb" object. By default it will look like this:

{
    TableName => 'starch_states',
    ProvisionedThroughput => {
        ReadCapacityUnits  => 1,
        WriteCapacityUnits => 1,
    },
    AttributeDefinitions => [{
        AttributeName => $key_field,
        AttributeType => 'S',
    }],
    KeySchema => [{
        AttributeName => $key_field,
        KeyType       => 'HASH',
    }],
}

Any arguments you pass will override those in the returned arguments, which means you could, for example, do something like this to override the provisioned units:

my $args = $store->create_table_args(
    ProvisionedThroughput => {
        ReadCapacityUnits  => 100,
        WriteCapacityUnits => 20,
    },
);

create_table

Creates the "table" by passing any arguments to "create_table_args" and calling the CreateTable method on the "ddb" object.

This method will not return until the new table is in an ACTIVE state.

If no exceptions are thrown a Paws::DynamoDB::TableDescription object is returned.

set

Set "set" in Starch::Store.

get

Set "get" in Starch::Store.

remove

Set "remove" in Starch::Store.

SUPPORT

Please submit bugs and feature requests to the Starch-Store-Paws-DynamoDB GitHub issue tracker:

https://github.com/bluefeet/Starch-Store-Paws-DynamoDB/issues

AUTHOR

Aran Clary Deltac <bluefeet@gmail.com>

ACKNOWLEDGEMENTS

Thanks to ZipRecruiter for encouraging their employees to contribute back to the open source ecosystem. Without their dedication to quality software development this distribution would not exist.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.