Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An ActiveRecord like interface for SimpleDB. Can be used as a drop in replacement for ActiveRecord in rails.
Ruby Shell
Pull request Compare This branch is 1 commit ahead, 304 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_strings :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_strings :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_strings :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_strings :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


Domain Prefix

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


Connection Modes

There are 4 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.
  • pool - NOT IMPLEMENTED YET - opens a maximum number of connections and round robins them for any simpledb request.

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


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

Something went wrong with that request. Please try again.