Fork me on GitHub



Static Model provides ActiveRecord like functionalities while reading from a simple YAML file.


There are sometimes when you need records that are completely immutable or need to travel very easily with your app. One of the problems with storing all your data in a database is that you can’t really make assumptions about certain records existing. StaticModel provides a very easy way to create models that act just like ActiveRecord, but are reading off of static YAML files that can exist in your app/repository.


StaticModel is a gem and can be used in any Ruby project, but it was designed around being used in Rails. The instructions that follow are Rails specific, but to use it in any Ruby app would not be much different.

The first thing to do is set up your model. In app/models/ create a model just like you would with an AR model. For example, lets create a Book model:

# app/models/book.rb
class Book < StaticModel::Base


StaticModels descend from StaticModel::Base. Without any config, this model makes some assumptions. It assumes you have a YAML file in config/data/TABLE_NAME.yml. The table name is assumed to be the lower-cased plural of the model name (just like Rails DB tables). For example, for our Book model, we would have a YAML file config/data/books.yml. If you want the file living somewhere else, or names something completely different, just use the macro: set_data_file

class Book < StaticModel::Base
  set_data_file '/path/to/my/file/withanothername.yml'

The format of the YAML file is very simple. StaticModel just expects an array of YAML hashses. The only requirement is that each of these hashes has an ‘id’ with a unique integer.

For example, heres our books.yml

- id: 1
  title: The Ruby Way
  author: Hal Fulton
- id: 2
  title: Programming Ruby
  author: Dave Thomas
  publisher: Pragmatic Programmers

With this set up, we can now query our data using almost identical methods to AR.

>> Book.find(1)
=> #<Book:0x1706fd8 @attributes={:author=>"Hal Fulton", :title=>"The Ruby Way"}, id1

>> Book.first
=> #<Book:0x1706fd8 @attributes={:author=>"Hal Fulton", :title=>"The Ruby Way"}, id1

>> Book.find(:all) (or Book.all)
=> [#<Book:0x1706fd8 @attributes={:author=>"Hal Fulton", :title=>"The Ruby Way"}, id1, 
  #<Book:0x1706fc4 @attributes={:author=>"Dave Thomas", :title=>"Programming Ruby", :publisher=>"Pragmatic Programmers"}, id2]

>> Book.find_by_title('The Ruby Way')
=> #<Book:0x1706fd8 @attributes={:author=>"Hal Fulton", :title=>"The Ruby Way"}, id1

>> b = Book.first
>> b.title
=> "The Ruby Way"
=> 1

Theres also some primitive association support (more coming): Currently StaticModel supports has_many and belongs_to. This can work between StaticModels or between a StaticModel and an ActiveRecord model.

Lets say our Books have many Readers. Book is our StaticModel, but a Reader is an ActiveRecord model.

class Reader < ActiveRecord::Base
  belongs_to :book, :foreign_key => 'book_id'

This means that the readers table in our DB has a book_id column that refers to the IDs we used in our books.yml.

>> r = Reader.create(:name => 'Aaron Quint', :book_id => 1)
=> #<Reader>
=> #<Book:0x1706fd8 @attributes={:author=>"Hal Fulton", :title=>"The Ruby Way"}, id1

This also works the other way around.

class Book < StaticModel::Base
  has_many :readers

has_many in StaticModel uses scoped if available. This means that you can use the power of chained scope associations and minimize queries.

>> Book.first.readers # Fires off a single query
>> Book.first.readers.find(:all, :conditions => ['created_at < ?',]) # Still only 1 query


sudo gem install static_model

Or directly from github:

sudo gem install quirkey-static_model -s

Github in thier infinite awesomeness also lets you download the source in multiple formats.

Bugs/Feature Requests

The full and most up to date source is at github:

You can clone or fork from there to fix or break the code. The tests are written using the Shoulda gem, so youll need that in order to run the tests.

I’m happy to take feature requests/bug reports. Just email me (contact below) or message me on github.


This code is free to use under the terms of the MIT license.


Feel free to email me at aaron at quirkey dot com.

Please check out my blog.

If you like or use this library – I don’t want donations – but you can recommend me on or hire me to work on your next project.