Net::Amazon::DynamoDB
version 0.002001
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;
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.
Net::Amazon::DynamoDB - Simple interface for Amazon DynamoDB
The table definitions
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::ConnCache
LWP::UserAgent
Contains LWP::UserAgent instance.
Contains JSON instance for decoding/encoding json.
JSON
JSON object needs to support: canonical, allow_nonref and utf8
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
dynamodb.us-east-1.amazonaws.com
AWS API access key
Required!
AWS API secret key
AWS API Version. Use format "YYYYMMDD"
Default: 20111205
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)
Table prefix, prepended before table name on usage
Default: ''
Whether database errors (eg 4xx Response from DynamoDB) raise errors or not.
Default: 0
Amount of retries a query will be tries if ProvisionedThroughputExceededException is raised until final error.
Default: 0 (do only once, no retries)
Whether we parse results using table definition (faster) or without a known definition (still requires table definition for indexes)
Wait period in seconds between tries. Float allowed.
Default: 0.1 (100ms)
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: -
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.
Which one to use. Either sha1_hex, sha256_hex, sha384_hex or coderef
Default: sha1_hex
The x-amzn-RequestId header returned by the service. This is needed by Amazon tech support for debugging service issues
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
$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 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"; } }
HashRef in the form
{ table_name => { put => [ { attribs }, .. ], delete => [ { primary keys } ] } }
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
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 } } );
$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 HashRef
HashRef of options
return_mode
Can be set to on of "ALL_OLD", "UPDATED_OLD", "ALL_NEW", "UPDATED_NEW"
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";
$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 }
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.
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"; } }
HashRef of tablename => primary key ArrayRef
Batch request might not fetch all requested items at once. This switch enforces to batch get the unprocessed items.
Deletes a single item by primary key (hash or hash+range key).
# only with hash key
$where_ref
HashRef containing at least primary key. Can also contain additional attribute filters
HashRef containing options
Bool whether return old, just deleted item or not
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 );
$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.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
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" }
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)
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
Arbitrary request to DynamoDB API
Get/set last error
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 (c) 2012 the "AUTHOR" as listed above
Same license as Perl itself.
Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
This software is copyright (c) 2017 by Ulrich Kautz.
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.