Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lsegal/odb

ODB: A Ruby Object Database
https://github.com/lsegal/odb

Last synced: about 2 months ago
JSON representation

ODB: A Ruby Object Database

Awesome Lists containing this project

README 

        
= ODB: A Ruby Object Database



== Synopsis



ODB attempts to be a transparent persistence layer in the Ruby interpreter

inspired by Object Oriented Databases like Python's Zope Object Database and

more recently, MagLev. The goal is to make object persistence as invisible

as possible in Ruby, though full transparency (as MagLev attempts) can

never really be possible.



== Features



ODB supports:



* Transparent Persistent Objects

* ACID Transactions

* Implicit Key Names

* Lazy Loading of Attributes



== Quick Start



ODB looks very similar to a standard key-value store database such as 

Memcached, Redis, or Tokyo Tyrant. For instance, we create a database

and access objects by key names as follows:



  require 'odb'

  

  db = ODB.new

  db[:key] = "Hello"

  # and now...

  db[:key] == "Hello" # => true

  

This is very basic usage. Unlike key-value stores, however, it is possible

to store and access objects implicitly, without directly assigning them

a key. We will see this more with persistent objects

  

== Transparent Persistent Objects



Persistent objects allow a more transparent form of storing objects. To

mark a method as persistent, simply include the +Persistent+ module:



  class Post

    include ODB::Persistent

    

    attr_accessor :title, :body

    

    def initialize(title, body)

      super() # needed for Persistent's constructor

      @title, @body = title, body

    end

  end

  

You can now benefit from transparent saves in transactions.



== ACID Transactions



ODB supports very basic transactions right now. A simple example of a

transaction is:



  db = ODB.new

  db.transaction do

    post = Post.new("foo", "bar")

  end

  

At this point, the +Post+ object will now be persisted either in memory or

on disk (whichever datastore you use). This implicit storage only works for

newly created objects, not modified ones. If post were to be modified, it

would need to be marked for a save. Hopefully this API can also become more

transparent, though it seems unlikely with Ruby's object model. To save

a modified object, queue it:



  db.transaction do

    post.title = "something else"

    post.__queue__

  end

  

Transactions occur in an all-or-nothing fashion, so if an exception is raised

in the middle of a save, nothing will be persisted:



  db.transaction do

    db[:post1] = Post.new

    raise "exception!"

    db[:post2] = Post.new

  end

  

  db[:post1] # => nil

  db[:post2] # => nil

  

== Implict Key Names



You may be wondering how to read the post back out after it's been persisted

to disk. This is why symbolic key-names are used in key-value stores. We can

use the following to save the object to a specific symbolic name as we

did in the first example:



  db[:key] = post

  

However we can create generalized key names for any new post object, to

implicitly key any saved post object by a symbolic determinate name. All

we need to do is override +__serialize_key__+ to return a Symbol:



  class Post

    def __serialize_key__; title.to_sym end

  end



Here we return the title, since we assume it is unique for the purpose of

this example. Now when we do:



  posts = []

  db.transaction do

    posts << Post.new("title1", "body1")

    posts << Post.new("title2", "body2")

  end

  

We can access both objects as:



  db[:title1] # => #

  db[:title2] # => #

  

== Lazy Loading of Attributes



ODB can perform lazy-loading on any standard Ruby attribute. When an object

is deserialized, each instance variable is checked to see if there is a 

zero-argument method by the same name. If so, it (temporarily) replaces the

method with a stub that will lazily load the object when the attribute is

read. Consider this example:



  class Post

    include ODB::Persistent

    attr_accessor :title, :comments



    def initialize(title) 

      super()

      @comments = [] 

      @title = title

    end

  

    def __serialize_key__; @title.to_sym end

  end



  # Create a post with 100 comments

  db = ODB.new

  db.transaction do

    post = Post.new("hello")

    100.times {|i| post.comments << "This is comment ##{i}" }

  end



  db.clear_cache # force de-serialization 

  p db[:hello]

  # => #

  p db[:hello].title 

  # => "hello"

  p db[:hello].comments

  # => ["This is comment #0", "This is comment #1", ...]

  

One of the benefits of shallow reads (a.k.a. lazy loading) is that you're not

immediately deserializing associations. If you had a complex object structure

that held cyclic associations or associations to a root object in your tree,

you could end up de-serializing the entire database in one read, which would

obviously not be a good thing. ODB's lazy attributes allow reads on an object

to be very fast while maintaining associations transparently.



== The Supported Data Stores



Currently ODB has support for in-memory, on-disk, JSON (also on-disk) and

redis data stores. One benefit is that it is possible to write a wrapper for 

any key-value data store such as memcached, mongo, etc.. To implement a

data store, you just need to implement the +read_object+ and +write_object+

methods in the +Database+ class.



== Copyright & License



Copyright Loren Segal © 2009, licensed under the {file:LICENSE MIT License}