NAME

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

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.

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'
            }
        },
        
        # 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 unites
$ddb->exists_table( $_ ) || $ddb->create_table( $_, 10, 5 )
    for qw/ sometable othertable /;

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

CLASS ATTRIBUTES

tables

The table definitions

lwp

Contains LWP::UserAgent instance.

json

Contains JSON instance for decoding/encoding json.

host

DynamoDB API Hostname

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

access_key

AWS API access key

secret_key

AWS API secret key

read_consistent

Whether reads (get_item) consistent per default or not. This does not affcect batch_get_item or 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

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], [$return_old]

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

  {}

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

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

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

# write conditionally
$ddb->update_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

• $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

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";

batch_get_item

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";
    }
}

delete_item

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

# only with hash key

query_items $table, $where, $args

Search in a table with hash AND range key.

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

• $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.amazonwebservices.com/amazondynamodb/latest/developerguide/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)

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.amazonwebservices.com/amazondynamodb/latest/developerguide/API_Scan.html

request

Arbitrary request to DynamoDB API

error [$str]

Get/set last error

AUTHOR

Ulrich Kautz <uk@fortrabbit.de>

COPYRIGHT

Copyright (c) 2011 the "AUTHOR" as listed above

LICENCSE

Same license as Perl itself.

cpanm Net::Amazon::DynamoDB

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