NAME

Net::Amazon::DynamoDB

VERSION

version 0.002001

SYNOPSIS

my $ddb = Net::Amazon::DynamoDB->new(
    access_key => $my_access_key,
    secret_key => $my_secret_key,
    tables     => {

        # table with only hash key
        sometable => {
            hash_key   => 'id',
            attributes => {
                id          => 'N',
                name        => 'S',
                binary_data => 'B'
            }
        },

        # table with hash and reange key key
        othertable => {
            hash_key   => 'id',
            range_key  => 'range_id',
            attributes => {
                id       => 'N',
                range_id => 'N',
                attrib1  => 'S',
                attrib2  => 'S'
            }
        }
    }
);

# create both tables with 10 read and 5 write units
$ddb->exists_table( $_ ) || $ddb->create_table( $_, 10, 5 )
    for qw/ sometable othertable /;

# insert something into tables
$ddb->put_item( sometable => {
    id         => 5,
    name       => 'bla',
    binary_data => $some_data
} ) or die $ddb->error;
$ddb->put_item( othertable => {
    id        => 5,
    range_id  => 7,
    attrib1   => 'It is now '. localtime(),
    attrib2   => 'Or in unix timstamp '. time(),
} ) or die $ddb->error;

DESCRIPTION

Simple to use interface for Amazon DynamoDB

If you want an ORM-like interface with real objects to work with, this is implementation is not for you. If you just want to access DynamoDB in a simple/quick manner - you are welcome.

See https://github.com/ukautz/Net-Amazon-DynamoDB for latest release.

NAME

Net::Amazon::DynamoDB - Simple interface for Amazon DynamoDB

CLASS ATTRIBUTES

tables

The table definitions

use_keep_alive

Use keep_alive connections to AWS (Uses LWP::ConnCache experimental mechanism). 0 to disable, positive number sets value for LWP::UserAgent attribute 'keep_alive' Default: 0

lwp

Contains LWP::UserAgent instance.

json

Contains JSON instance for decoding/encoding json.

JSON object needs to support: canonical, allow_nonref and utf8

host

DynamoDB API Hostname. Your table will be in this region only. Table names do not have to be unique across regions. This is how you specify other regions. See Amazon's documentation for other available endpoints.

Default: dynamodb.us-east-1.amazonaws.com

access_key

AWS API access key

Required!

secret_key

AWS API secret key

Required!

api_version

AWS API Version. Use format "YYYYMMDD"

Default: 20111205

read_consistent

Whether reads (get_item, batch_get_item) consistent per default or not. This does not affect scan_items or query_items, which are always eventually consistent.

Default: 0 (eventually consistent)

namespace

Table prefix, prepended before table name on usage

Default: ''

raise_error

Whether database errors (eg 4xx Response from DynamoDB) raise errors or not.

Default: 0

max_retries

Amount of retries a query will be tries if ProvisionedThroughputExceededException is raised until final error.

Default: 0 (do only once, no retries)

derive_table

Whether we parse results using table definition (faster) or without a known definition (still requires table definition for indexes)

Default: 0

retry_timeout

Wait period in seconds between tries. Float allowed.

Default: 0.1 (100ms)

cache

Cache object using Cache interface, eg Cache::File or Cache::Memcached

If set, caching is used for get_item, put_item, update_item and batch_get_item.

Default: -

cache_disabled

If cache is set, you still can disable it per default and enable it per operation with "use_cache" option (see method documentation) This way you have a default no-cache policy, but still can use cache in choosen operations.

Default: 0

cache_key_method

Which one to use. Either sha1_hex, sha256_hex, sha384_hex or coderef

Default: sha1_hex

request_id

The x-amzn-RequestId header returned by the service. This is needed by Amazon tech support for debugging service issues

METHODS

create_table $table_name, $read_amount, $write_amount

Create a new Table. Returns description of the table

my $desc_ref = $ddb->create_table( 'table_name', 10, 5 )
$desc_ref = {
    count           => 123,         # amount of "rows"
    status          => 'CREATING',  # or 'ACTIVE' or 'UPDATING' or some error state?
    created         => 1328893776,  # timestamp
    read_amount     => 10,          # amount of read units
    write_amount    => 5,           # amount of write units
    hash_key        => 'id',        # name of the hash key attribute
    hash_key_type   => 'S',         # or 'N',
    #range_key      => 'id',        # name of the hash key attribute (optional)
    #range_key_type => 'S',         # or 'N' (optional)
}

delete_table $table

Delete an existing (and defined) table.

Returns bool whether table is now in deleting state (succesfully performed)

describe_table $table

Returns table information

my $desc_ref = $ddb->describe_table( 'my_table' );
$desc_ref = {
    existing        => 1,
    size            => 123213,      # data size in bytes
    count           => 123,         # amount of "rows"
    status          => 'ACTIVE',    # or 'DELETING' or 'CREATING' or 'UPDATING' or some error state
    created         => 1328893776,  # timestamp
    read_amount     => 10,          # amount of read units
    write_amount    => 5,           # amount of write units
    hash_key        => 'id',        # name of the hash key attribute
    hash_key_type   => 'S',         # or 'N',
    #range_key      => 'id',        # name of the hash key attribute (optional)
    #range_key_type => 'S',         # or 'N' (optional)
}

If no such table exists, return is

{
    existing => 0
}

update_table $table, $read_amount, $write_amount

Update read and write amount for a table

exists_table $table

Returns bool whether table exists or not

list_tables

Returns tables names as arrayref (or array in array context)

put_item $table, $item_ref, [$where_ref], [$args_ref]

Write a single item to table. All primary keys are required in new item.

# just write
$ddb->put_item( my_table => {
    id => 123,
    some_attrib => 'bla',
    other_attrib => 'dunno'
} );

# write conditionally
$ddb->put_item( my_table => {
    id => 123,
    some_attrib => 'bla',
    other_attrib => 'dunno'
}, {
    some_attrib => { # only update, if some_attrib has the value 'blub'
        value => 'blub'
    },
    other_attrib => { # only update, if a value for other_attrib exists
        exists => 1
    }
} );

$table

Name of the table
$item_ref

Hashref containing the values to be inserted
$where_ref [optional]

Filter containing expected values of the (existing) item to be updated
$args_ref [optional]

HashRef with options
- return_old
  
  If true, returns old value
- no_cache
  
  Force not using cache, if enabled per default
- use_cache
  
  Force using cache, if disabled per default but setupped

batch_write_item $tables_ref, [$args_ref]

Batch put / delete items into one ore more tables.

Caution: Each batch put / delete cannot process more operations than you have write capacity for the table.

Example:

my ( $ok, $unprocessed_count, $next_query_ref ) = $ddb->batch_write_item( {
    table_name => {
        put => [
            {
                attrib1 => "Value 1",
                attrib2 => "Value 2",
            },
            # { .. } ..
        ],
        delete => [
            {
                hash_key => "Hash Key Value",
                range_key => "Range Key Value",
            },
            # { .. } ..
        ]
    },
    # table2_name => ..
} );

if ( $ok ) {
    if ( $unprocessed_count ) {
        print "Ok, but $unprocessed_count still not processed\n";
        $ddb->batch_write_item( $next_query_ref );
    }
    else {
        print "All processed\n";
    }
}

$tables_ref

HashRef in the form

{ table_name => { put => [ { attribs }, .. ], delete => [ { primary keys } ] } }

$args_ref

HashRef

process_all

Keep processing everything which is returned as unprocessed (if you send more operations than your table has write capability or you surpass the max amount of operations OR max size of request (see AWS API docu)).

Caution: Error handling

Default: 0

update_item $table, $update_ref, $where_ref, [$args_ref]

Update existing item in database. All primary keys are required in where clause

# update existing
$ddb->update_item( my_table => {
    some_attrib => 'bla',
    other_attrib => 'dunno'
}, {
    id => 123,
} );

# write conditionally
$ddb->update_item( my_table => {
    some_attrib => 'bla',
    other_attrib => 'dunno'
}, {
    id => 123,
    some_attrib => { # only update, if some_attrib has the value 'blub'
        value => 'blub'
    },
    other_attrib => { # only update, if a value for other_attrib exists
        exists => 1
    }
} );

$table

Name of the table

$update_ref

Hashref containing the updates.

delete a single values
```
{ attribname => undef }
```

replace a values

{
    attribname1 => 'somevalue',
    attribname2 => [ 1, 2, 3 ]
}

add values (arrays only)
```
{ attribname => \[ 4, 5, 6 ] }
```

$where_ref [optional]

Filter HashRef
$args_ref [optional]

HashRef of options
- return_mode
  
  Can be set to on of "ALL_OLD", "UPDATED_OLD", "ALL_NEW", "UPDATED_NEW"
- no_cache
  
  Force not using cache, if enabled per default
- use_cache
  
  Force using cache, if disabled per default but setupped

get_item $table, $pk_ref, [$args_ref]

Read a single item by hash (and range) key.

# only with hash key
my $item1 = $ddb->get_item( my_table => { id => 123 } );
print "Got $item1->{ some_key }\n";

# with hash and range key, also consistent read and only certain attributes in return
my $item2 = $ddb->get_item( my_other_table =>, {
    id    => $hash_value, # the hash value
    title => $range_value # the range value
}, {
    consistent => 1,
    attributes => [ qw/ attrib1 attrib2 ]
} );
print "Got $item2->{ attrib1 }\n";

$table

Name of the table

$pk_ref

HashRef containing all primary keys

# only hash key
{
    $hash_key => $hash_value
}

# hash and range key
{
    $hash_key => $hash_value,
    $range_key => $range_value
}

$args_ref [optional]

HashRef of options
- consistent
  
  Whether read shall be consistent. If set to 0 and read_consistent is globally enabled, this read will not be consistent
- attributes
  
  ArrayRef of attributes to read. If not set, all attributes are returned.
- no_cache
  
  Force not using cache, if enabled per default
- use_cache
  
  Force using cache, if disabled per default but setupped

batch_get_item $tables_ref, [$args_ref]

Read multiple items (possible accross multiple tables) identified by their hash and range key (if required).

my $res = $ddb->batch_get_item( {
    table_name => [
        { $hash_key => $value1 },
        { $hash_key => $value2 },
        { $hash_key => $value3 },
    ],
    other_table_name => {
        keys => [
            { $hash_key => $value1, $range_key => $rvalue1 },
            { $hash_key => $value2, $range_key => $rvalue2 },
            { $hash_key => $value3, $range_key => $rvalue3 },
        ],
        attributes => [ qw/ attrib1 attrib2 / ]
    ]
} );

foreach my $table( keys %$res ) {
    foreach my $item( @{ $res->{ $table } } ) {
        print "$item->{ some_attrib }\n";
    }
}

$tables_ref

HashRef of tablename => primary key ArrayRef

$args_ref

HashRef

process_all

Batch request might not fetch all requested items at once. This switch enforces to batch get the unprocessed items.

Default: 0

delete_item $table, $where_ref, [$args_ref]

Deletes a single item by primary key (hash or hash+range key).

# only with hash key

$table

Name of the table
$where_ref

HashRef containing at least primary key. Can also contain additional attribute filters
$args_ref [optional]

HashRef containing options
- return_old
  
  Bool whether return old, just deleted item or not
  
  Default: 0
- no_cache
  
  Force not using cache, if enabled per default
- use_cache
  
  Force using cache, if disabled per default but setupped

query_items $table, $where, $args

Search in a table with hash AND range key.

my ( $count, $items_ref, $next_start_keys_ref )
    = $ddb->query_items( some_table => { id => 123, my_range_id => { GT => 5 } } );
print "Found $count items, where last id is ". $items_ref->[-1]->{ id }. "\n";

# iterate through al all "pages"
my $next_start_keys_ref;
do {
    ( my $count, my $items_ref, $next_start_keys_ref )
        = $ddb->query_items( some_table => { id => 123, my_range_id => { GT => 5 } }, {
            start_key => $next_start_keys_ref
        } );
} while( $next_start_keys_ref );

$table

Name of the table
$where

Search condition. Has to contain a value of the primary key and a search-value for the range key.

Search-value for range key can be formated in two ways
- Scalar
  
  Eg
```
{ $range_key_name => 123 }
```
  Performs and EQ (equal) search
- HASHREF
  
  Eg
```
{ $range_key_name => { GT => 1 } }
{ $range_key_name => { CONTAINS => "Bla" } }
{ $range_key_name => { IN => [ 1, 2, 5, 7 ] } }
```
  See http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html
$args
```
{
    limit => 5,
    consistent => 0,
    backward => 0,
    #start_key =>  { .. }
    attributes => [ qw/ attrib1 attrib2 / ],
    #count => 1
}
```
HASHREF containing:
- limit
  
  Amount of items to return
  
  Default: unlimited
- consistent
  
  If set to 1, consistent read is performed
  
  Default: 0
- backward
  
  Whether traverse index backward or forward.
  
  Default: 0 (=forward)
- start_key
  
  Contains start key, as return in LastEvaluatedKey from previous query. Allows to iterate above a table in pages.
```
{ $hash_key => 5, $range_key => "something" }
```
- attributes
  
  Return only those attributes
```
[ qw/ attrib attrib2 / ]
```
- count
  
  Instead of returning the actual result, return the count.
  
  Default: 0 (=return result)
- all
  
  Iterate through all pages (see link to API above) and return them all.
  
  Can take some time. Also: max_retries might be needed to set, as a scan/query create lot's of read-units, and an immediate reading of the next "pages" lead to an Exception due to too many reads.
  
  Default: 0 (=first "page" of items)

scan_items $table, $filter, $args

Performs scan on table. The result is eventually consistent. Non hash or range keys are allowed in the filter.

See query_items for argument description.

Main difference to query_items: A whole table scan is performed, which is much slower. Also the amount of data scanned is limited in size; see http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html

request

Arbitrary request to DynamoDB API

error [$str]

Get/set last error

AUTHOR

Ulrich Kautz <uk@fortrabbit.de>
Thanks to MadHacker http://stackoverflow.com/users/1139526/madhacker (the signing code in request method)
Benjamin Abbott-Scoot <benjamin@abbott-scott.net> (Keep Alive patch)

COPYRIGHT

LICENCSE

Same license as Perl itself.

AUTHORS

Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
Ulrich Kautz <uk@fortrabbit.de>

COPYRIGHT AND LICENSE

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

To install Net::Amazon::DynamoDB, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::Amazon::DynamoDB

CPAN shell

perl -MCPAN -e shell
install Net::Amazon::DynamoDB

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

NAME

CLASS ATTRIBUTES

tables

use_keep_alive

lwp

json

host

access_key

secret_key

api_version

read_consistent

namespace

raise_error

max_retries

derive_table

retry_timeout

cache

cache_disabled

cache_key_method

request_id

METHODS

create_table $table_name, $read_amount, $write_amount

delete_table $table

describe_table $table

update_table $table, $read_amount, $write_amount

exists_table $table

list_tables

put_item $table, $item_ref, [$where_ref], [$args_ref]

batch_write_item $tables_ref, [$args_ref]

update_item $table, $update_ref, $where_ref, [$args_ref]

get_item $table, $pk_ref, [$args_ref]

batch_get_item $tables_ref, [$args_ref]

delete_item $table, $where_ref, [$args_ref]

query_items $table, $where, $args

scan_items $table, $filter, $args

request

error [$str]

AUTHOR

COPYRIGHT

LICENCSE

AUTHORS

COPYRIGHT AND LICENSE

Module Install Instructions