README

= dm-simpledb

Written by Edward Ocampo-Gooding

An experimental DataMapper adapter for SimpleDB. Currently unfit for use.

Tested using Matthew Painter’s SimpleDB/dev http://code.google.com/p/simpledb-dev/
Additional SimpleDB/dev setup notes found here: http://pandastream.tumblr.com/post/52779609/playing-with-panda-without-simpledb-account

Greatly inspired by Jeremy Boles' dm-adapter-simpledb

== Current state

  When starting this project, I assumed that SimpleDB allowed queries to span more than one domain. I was terribly wrong.

  In lieu of that, this SimpleDB adapter follows the Single Table Inheritance pattern espoused by articles online and seen in a variety of similar libraries (see Bibliography). What a bummer.

== Future goals

  * Parallelized queries for increased throughput
  * Support of normalized 1:1 table:domain schemes that works with associations
  * Local caching of results using something like query strings for cache keys

== Usage
  
  === Standalone
  
    require 'rubygems'
    require 'dm-core'
    
    DataMapper.setup(:default, 'simpledb://sdb.amazon.com/sweetapp_development', :access_key_id => 'a valid access key id', :secret_access_key => 'a valid secret access key id')
    
    [Same as the following, but skip the database.yml]
    
  === In a Merb application
  
    Setup database.yml with the SimpleDB DataMapper adapter:

      adapter:  simpledb
      database: 'default'
      access_key_id: (a 20-character, alphanumeric sequence)
      secret_access_key: (a 40-character sequence)
      domain: 'sweetapp_development'
      base_url: 'http://sdb.amazon.com'

    Alternatively, 

    Create a model
  
      class Tree
        include DataMapper::Resource
      
        storage_name "trees"  # manually setting the domain
      
        property :id,   Integer, :serial => true
        property :name, String, :nullable => false
      end

    Use interactively (with merb -i)
  
    $ merb -i
  
      maple = Tree.new
      maple.name = "Acer rubrum"
      maple.save
    
      all_trees = Tree.all() # calls #read_all
      a_tree = Tree.first(:name => "Acer rubrum")
      yanked_tree = Tree.remote(:name => "Acer rubrum")

== Bibliography
  Relating to Amazon SimpleDB http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1292&ref=featured
    Approaching SimpleDB from a relational database background
  
  Active Record Persistence with Amazon SimpleDB http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1367&categoryID=152
  
  Building for Performance and Reliability with Amazon SimpleDB  http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1394&categoryID=152
  
  Query 101: Building Amazon SimpleDB Queries  http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1231&categoryID=152
  
  Query 201: Tips & Tricks for Amazon SimpleDB Query  http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1232&categoryID=152
    Latter portion describes parallelization advantages of normalized domains – the downside being the added complexity at the application layer (this library’s).
  
  Using SimpleDB and Rails in No Time with ActiveResource  http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1242&categoryID=152
    Exemplifies using the Single Table Inheritance pattern within a single SimpleDB domain by storing the model type in an attribute called '_resource' and using a “SHA512 hash function on the request body combined with a timestamp and a configurable salt” for the id.
  
  RightScale Ruby library to access Amazon EC2, S3, SQS, and SDB  http://developer.amazonwebservices.com/connect/entry!default.jspa?categoryID=140&externalID=1014&fromSearchPage=true