cstar / erlsdb

ErlSDB README
-------------
This code is an overhaul of Shahzad Bhatti's original code (apparently not maintained anymore).

Summary
-----------
Amazon SimpleDB is a web service for running queries on structured data 
in real time. See aws.amazon.com/simpledb.
This erlsdb library provides interface to access SimpleDB web service using
REST APIs.

Author:  Shahzad Bhatti <bhatti@plexobject.com>
Author: Eric Cestari <eric@ohmforce.com>
Version: 1.0
Date:    2009/02/23

Requirements
------------

- OTP-R12B (http://erlang.org/download.html)

- An Amazon Web Services account - See http://www.amazonaws.com


Features
---------
- Uses Signature V2
- Multiple servers are ran (default : 5)
- HTTP calls are asynchronous, per server.
- SSL support enabled by default (for deactivating see example usage below)
- Full support of the SimpleDB API version 2007-11-07

TODO
-----
- Update documentation
- Implement a type system as described by James Murty in his book

License
-------

Released under the GNU General Public License v2.

= BUILDING =

Type rake.
The first time, you will need to edit erlang_config.rb.
Re-run rake

= Configuration = 

You'll need to set your credentials to Amazon SDB :
- by passing them as OTP application parameters or
- by setting the AMAZON_ACCESS_KEY_ID and AMAZON_SECRET_ACCESS_KEY environment variable

= Running the incomplete test suite =
Set the AMAZON_ACCESS_KEY_ID and AMAZON_SECRET_ACCESS_KEY environment variables

erl -boot start_sasl -pa lib/erlsdb/ebin -pa lib/erlsdb/test/ -s erlsdb_test test -s init stop

Expected output (if you did not create any domains previously): 
Listing domains {ok,[],nil}
Creating test domain ["TestDomain"]
Adding attributes [{"City","Seattle"},
                   {"State","WA"},
                   {"StreetAddress","705 5th Ave"},
                   {"Zip","98101"}]
Removing attributes ok
Removing test domain []


= A FEW EXAMPLES = 

# SSL is deactivated in the following : 
erl -boot release_local/erlsdb-initial -erlsdb access '"<AWS_ACCESS_ID>"' secret '"<AWS_SECRET_KEY>"' ssl false
1> erlsdb:create_domain("fubar").
nil
2> erlsdb:list_domains().
{ok,["fubar"],[]}
3> erlsdb:put_attributes("fubar", "test", [{"foo", "bar"}]).
nil
4> erlsdb:get_attributes("fubar", "test").
{ok,[{"foo","bar"}]}
..
5> erlsdb:select("select count(*) from domain where toto = 'truc'",nil).
{ok,[{"Domain",[{"Count","2"}]}],nil}

6> erlsdb:domain_metadata("domain").
{ok,[{"Timestamp",1235403601},
     {"ItemCount",4},
     {"AttributeValueCount",8},
     {"AttributeNameCount",4},
     {"ItemNamesSizeBytes",24},
     {"AttributeValuesSizeBytes",20},
     {"AttributeNamesSizeBytes",19}]}
6> erlsdb:list_domains(nil,1). % paging works
{ok,["domain"],"ZnViYXI="}
7> erlsdb:list_domains("ZnViYXI=",1).
{ok,["fubar"],nil}

8> erlsdb:select("select count(*) from domain where toto = 'truc'",nil).
{ok,[{"Domain",[{"Count","2"}]}],nil}

9> erlsdb:select("select * from blobs where toto = 'truc'",nil).
{ok,[{"blob1",[{"toto","truc"},{"foo","bar"}]},
     {"blob2",[{"toto","truc"},{"foo","bar"}]}],
    nil}
= About building = 
(Extract from charpi's readme)

rake --tasks : to know all tasks

You'll need a configuration in which you'll have to put things specific to your installation.
A template of file is generated the first time you launch 'rake'

Here is some useful tasks:
rake erlang:modules: Compile all erlang source files (test included)
rake erlang:releases: Build a tarball for each rel file found in the directory tree
rake erlang:tests[name]: Run the eunit test for the application "name". If no name is given, 
     all applications are tested. If a file test.desc is find in the "app_name/test" directory, eunit will
     use it as eunit test description.
rake erlang:edoc[name]: Build the document for an application or all if 'name' is omitted
rake otp:new_application[name]: Create a new application squeleton
rake otp:start_local[name]: Start a release in the developper environment

rake otp:initial_targer[name,version]: Create a tarball with a 'ready' to deploy
     an erlang system running the release. To use the system, you have to provide
     2 startup files in a directory named 'release_config'. Look at the sample in the
     application sample_rake.
= Build Author = 
Nicolas Charpentier <open_source@charpi.net>