Net::Amazon::DynamoDB - Simple interface for Amazon DynamoDB
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.
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;
The table definitions
Contains LWP::UserAgent instance.
LWP::UserAgent
Contains JSON instance for decoding/encoding json.
JSON
DynamoDB API Hostname
Default: dynamodb.us-east-1.amazonaws.com
AWS API access key
AWS API secret key
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)
Table prefix, prepended before table name on usage
Default: ''
Whether database errors (eg 4xx Response from DynamoDB) raise errors or not.
Default: 0
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 an existing (and defined) table.
Returns bool whether table is now in deleting state (succesfully performed)
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 read and write amount for a table
Returns bool whether table exists or not
Returns tables names as arrayref (or array in array context)
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 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 } } );
$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 ] }
Filter
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";
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"; } }
Deletes a single item by primary key (hash or hash+range key).
# only with hash key
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";
$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
{ $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
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.
LastEvaluatedKey
{ $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)
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
Arbitrary request to DynamoDB API
Get/set last error
Ulrich Kautz <uk@fortrabbit.de>
Copyright (c) 2011 the "AUTHOR" as listed above
Same license as Perl itself.
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
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.