Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
An ActiveRecord like interface for SimpleDB. Can be used as a drop in replacement for ActiveRecord in rails.

This branch is 282 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


SimpleRecord - ActiveRecord for SimpleDB

An ActiveRecord interface for SimpleDB. Can be used as a drop in replacement for ActiveRecord in rails.

Discussion Group


Issue Tracking


Getting Started

  1. Install gems

ONE TIME: Be sure to add the new gemcutter source:

gem install gemcutter
gem tumble

THEN (you should have in your sources and it MUST be above

gem install simple_record
  1. Create a model

    require 'simple_record'
    class MyModel < SimpleRecord::Base
       has_attributes :name
       has_ints :age

More about ModelAttributes below.

  1. Setup environment

  2. Go to town

    # Store a model object to SimpleDB
    mm = = "Travis"
    mm.age = 32
    id =
    # Get an object from SimpleDB
    mm2 = MyModel.find(id)
    puts 'got=' + + ' and he/she is ' + mm.age.to_s + ' years old'
    # Or more advanced queries? mms = MyModel?.find(:all, ["age=?", 32], :order=>"name", :limit=>10)

Attributes and modifiers for models

NOTE: All objects will automatically have :id, :created, :updated attributes.


Add string attributes.

class MyModel < SimpleRecord::Base
  has_attributes :name

has_ints, has_dates and has_booleans

Lets simple_record know that certain attributes defined in has_attributes should be treated as integers, dates or booleans. This is required because SimpleDB only has strings so SimpleRecord needs to know how to convert, pad, offset, etc.

class MyModel < SimpleRecord::Base
  has_attributes :name
  has_ints :age, :height
  has_dates :birthday
  has_booleans :is_nerd


Creates a many-to-one relationship. Can only have one per belongs_to call.

class MyModel < SimpleRecord::Base
    belongs_to :school
    has_attributes :name
    has_ints :age, :height
    has_dates :birthday
    has_booleans :is_nerd

Which requires another class called 'School' or you can specify the class explicitly with:

belongs_to :school, :class_name => "Institution"

set_table_name or set_domain_name

If you want to use a custom domain for a model object, you can specify it with set_table_name (or set_domain_name).

class SomeModel < SimpleRecord::Base
    set_table_name :different_model


Querying is similar to ActiveRecord for the most part.

To find all objects that match conditions returned in an Array:

Company.find(:all, :conditions => ["created_at > ?", 10.days.ago], :order=>"name", :limit=>50)

To find a single object:

Company.find(:first, :conditions => ["name = ? AND division = ? AND created_at > ?", "Appoxy", "West", 10.days.ago ])

To count objects:

Company.find(:count, :conditions => ["name = ? AND division = ? AND created_at > ?", "Appoxy", "West", 10.days.ago ])

You can also the dynamic method style, for instance the line below is the same as the Company.find(:first....) line above:

Company.find_by_name_and_division("Appoxy", "West")

To find all:

Company.find_all_by_name_and_division("Appoxy", "West")

There are so many different combinations of the above for querying that I can't put them all here, but this should get you started.

You can get more ideas from here: Not everything is supported but a lot is.


Domain Prefix

To set a global prefix across all your models, use:


Connection Modes

There are 3 different connection modes:

  • per_request (default) - opens and closes a new connection to simpledb for every simpledb request. Not the best performance, but it's safe and can handle many concurrent requests at the same time (unlike single mode).
  • single - one connection across the entire application, not recommended unless the app is used by a single person.
  • per_thread - a connection is used for every thread in the application. This is good, but the catch is that you have to ensure to close the connection.

You set the mode when you call establish_connection:

SimpleRecord.establish_connection(AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY, :connection_mode=>:per_thread)

We recommend per_thread with explicitly closing the connection after each Rails request (not to be mistaken for a SimpleDB request) or pool for rails apps.

For rails, be sure to add this to your Application controller if using per_thread mode:

after_filter :close_sdb_connection

def close_sdb_connection

SimpleRecord on Rails

You don't really have to do anything except have your models extends SimpleRecord::Base instead of ActiveRecord::Base, but here are some tips you can use.

Change Connection Mode

Use per_thread connection mode and close the connection after each request.

after_filter :close_sdb_connection

def close_sdb_connection

Disable ActiveRecord so you don't have to setup another database

This is most helpful on windows so Rails doesn't need sqlite or mysql gems/drivers installed which are painful to install on windows. In environment.rb, add 'config.frameworks -= [ :active_record ]', should look something like: do |config|
  config.frameworks -= [ :active_record ]

Tips and Tricks and Things to Know

Automagic Stuff

Automatic common fields

Every object will automatically get the following attributes so you don't need to define them:

  • id - UUID string
  • created - set when first save
  • updated - set every time you save/update

belongs_to foreign keys/IDs are accessible without touching the database

If you had the following in your model:

belongs_to :something

Then in addition to being able to access the something object with:


or setting it with:

o.something = someo

You can also access the ID for something directly with:



o.something_id = x

Batch Save

To do a batch save using SimpleDB's batch saving feature to improve performance, simply create your objects, add them to an array, then call:



You can use any cache that supports the ActiveSupport::Cache::Store interface.

SimpleRecord::Base.cache_store = my_cache_store

If you want a simple in memory cache store, try: . It supports max cache size and timeouts. You can also use memcached or


Special thanks to Garrett Cox for creating Activerecord2sdb which SimpleRecord is based on:

Something went wrong with that request. Please try again.