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
<https://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region>.
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/A
PI_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
Copyright (c) 2012 the "AUTHOR" as listed above
LICENCSE
Same license as Perl itself.
AUTHORS
* Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
* Ulrich Kautz <uk@fortrabbit.de>
COPYRIGHT AND LICENSE
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.
