Introduction
Ruby is a wonderful object oriented language featuring a well designed syntax and advanced constructs to bring the joy back to programming. Creating the object model to describe your problem domain is easy, but making this model persistent is another story: you have to deal with relational databases and the SQL language.
RDBMS systems are a proven and robust technology for storing and querying data, but after experiencing the wonders of Ruby, it is hard not to wish for a better way to integrate the OOP and Relational paradigms.
Og makes your dream come true! Og stands for ObjectGraph and provides a transparent way to make your objects persistent while leveraging the full querying power of an RDBMS system. In fact, Og is designed to use an RDBMS system like MySQL or PostgreSQL to implement the actual data store where the objects are serialized.
But, enough with the techno-babble, lets walk through a simple example to give you a better idea of what Og can do.
Installing Og
The best way to install Og is through RubyGems. For example:
gem install og
In order to use Og with a specific RDBMS, you have to install the corresponding Ruby binding. A list of supported RDBMSs and information about the Ruby bindings can be found in the README file.
Alternatively, you can install a .tar.gz or .zip distribution. You can find these at the following URL:
www.rubyforge.com/projects/nitro
A Basic Blog Model
Blogs are in vogue. It seems that almost everyone is running a blog, and many try to code one from scratch. Well review the steps necessary to generate the persistence model for a blog application using Og.
Lets start by designing the objects well use. Our simple Blog will use these three objects:
class Category
attr_accessor :name
end
class Post
attr_accessor :title
attr_accessor :body
attr_accessor :author
end
class Comment
attr_accessor :title
attr_accessor :body
attr_accessor :author
end
As you can see, this is pure Ruby code. One of the features of Ruby is dynamic typing. When defining the attributes of our objects, we dont declare the actual type. However, in order to persist the model in SQL, we need to provide some hints to Og.
Og provides a replacement to the attr* family of methods to facilitate attaching metadata to the objects attributes. An attribute that contains metadata is called a property. For each attr* method, there is a corresponding prop* method. That is,
attr => prop
attr_accessor => prop_accessor
attr_reader => prop_reader
attr_writer => prop_writer
Here are the class definitions using the property mechanism:
require 'og'
class Category
prop_accessor :name, String
end
class Post
prop_accessor :title, String
prop_accessor :body, String
prop_accessor :author, String
prop_accessor :create_time, Time
prop_accessor :hits, Fixnum
end
class Comment
prop_accessor :title, String
prop_accessor :body, String
prop_accessor :author, String
prop_accessor :create_time, Time
end
Notice that the prop_accessor works similar to Rubys attr_accessor. Here are some examples:
prop :title, true, String
prop_reader :title, :body, :author, String
To make the definitions look even cleaner, Og provides the property alias:
class Category
property :name, String
end
class Post
property :title, String
property :body, String
property :author, String
property :create_time, Time
property :hits, Fixnum
end
class Comment
property :title, String
property :body, String
property :author, String
property :create_time, Time
end
This is most of the information that Og needs to manage these objects. Before we continue, we need to setup the actual RDBMS data store used by Og. Currently, Og has built-in adapters for PostgreSQL, MySQL, SQLite3, and Oracle. For this example, well use the PostgreSQL adapter, so add this code after the class definitions.
db = Og::Database.new(
:database => 'test',
:adapter => 'psql',
:user => 'postgres',
:password => 'navelrulez'
)
Now you are ready to save your first object into Postgres. Add the following code:
# create the object
p = Post.new
p.title = 'Hello'
p.body = 'World'
p.author = 'tml'
# save the object in the database
p.save
Thats it! Og works behind the scenes doing all the work for you. This simple command, p.save, does the following:
- Creates the database test if it doesn't exist.
- Creates a table to store Post objects if it doesn't exist. The tables columns map to the object properties.
- Creates SQL indices.
- Creates any needed sequences.
- Serializes the object into the table.
Issue the following SQL to see the result:
SELECT * FROM og_post
This is nice, but where does the #save method come from? Og uses Ruby's advanced introspection features to automatically 'enchant' class that define properties. An enchanted class provides several methods that will be discussed in the following text. These enchanted classes are called managed classes.
Before going on, lets look at another Og macro that eases object creation:
p = Post.create
Create automatically calls the save method. Here is another way to save the object:
db << p
or
db.save(p)
Lets create a Category object.
cat = Category.new
cat.name = 'Programming'
cat.save
If you investigate the generated og_category table, you will see an oid column which serves as the primary key. This column is added automatically by Og. You can use the oid values to lookup objects:
cat = Category[1] # loads the category object with oid = 1
or
cat = db.load(1, Category)
As a convenience, Og allows you to lookup the category using the special property name:
cat = Category['Programming']
You can lookup objects by name only if the name property is defined.
If you want to view Og's SQL, you can enable debug mode by setting this global debug (DBG) variable:
$DBG = true
Customizing the Schema and Defining Relations
Og makes our blog model persistent through a simple interface. The next step is to refine the schema and define relations between the objects:
class Post; end
class Comment; end
class Category
property :name, String
many_to_many :posts, Post
def initialize(title = nil)
@title = title
end
end
class Post
property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
property :body, String
property :author, String
property :create_time, Time
property :hits, Fixnum, :sql_index => true
has_many :comments, Comment
def initialize(title = nil, body = nil, author = nil)
@title, @body, @author = title, body, author
@create_time = Time.now
@hits = 0
end
end
class Comment
property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
property :body, String
property :author, String
property :create_time, Time
belongs_to :post, Post
def initialize(title = nil, body = nil, author = nil)
@title, @body, @author = title, body, author
@create_time = Time.now
end
end
Observe the :sql property option is used to refine the generated column type for the title property of Post, and how the :sql_index option is used to add an index to the generated table.
Notice that the initialize methods provide default values to all parameters. This is required for all managed objects.
Observe the many_to_many, has_many, and belongs_to macros. Og uses these macros to define the relations between standard Objects. In essence, Og defines a domain specific mini language. The following kinds of relations are supported:
- has_one: has one object of the given type.
- has_many: has many objects of the given type.
- belongs_to: belongs_to an object of the given type.
- many_to_many: defines a many-to-many relation. The corresponding rows in the database are linked through a join table.
- refers_to: refers to another object.
These macros generate the constructs needed to efficiently implement the corresponding relations. For example, the belongs_to macro generates the property that links to the parent. The many_to_many relation generates the join table that links the participating classes.
Note that we have to use forward definitions of Post and Comment to satisfy Rubys parser. Workarounds will be provided in a future version.
After defining these relations, using and querying the object model is easy:
cat = Category.create('Programming')
cat.add_post { |p|
p.title = 'Title'
p.body = 'Body'
}
cat.add_post { |p|
p.title = 'Another'
p.body = 'Hello'
}
cat.posts
=> [Post(Title), Post(Another)]
cat.posts[0].title
=> Title
cat.posts.size
=> 2
p = Post[1]
p.title
=> Title
p.categories[0].title
=> 'Programming'
c = Comment.new('hello', 'world', 'tml')
c.post = p
c.save
p.comments.size
=> 1
p.add_comment { |c|
c.title = 'Hi there'
}
p.comments[1].title
=> 'Hi there'
com = Comment.new('Hi there')
p.add_comment(com)
All the methods used in the above examples are generated automatically. These methods transparently modify the underlying SQL schema using efficient queries.
Og provides full access to all features of the underlying RDBMS. Look at the following:
post = Post.select("title='Title' and body='Body'")
post.size
=> 1
post.hits
=> 0
Updating existing objects is easy too:
p = Post[1]
p.title = 'Changed'
p.save
p = Post[1]
p.title
=> 'Changed'
You can also update specific properties, for example:
p = Post[1]
p.update_properties "body='Hello world'"
p = Post[1]
p.body
=> 'Hello world'
If you don't like a particular comment, you can easily delete it by doing the following:
Comment.delete(comment)
or
comment.delete!
or even
db.delete(comment)
To delete all comments for a posting, enter the following:
p.delete_all_comments
When deleting an object that participates in relations, Og tries to delete all objects that belong to this object (ie, cascade deletes).
All the generated methods take more parameters to customize their behaviour to suit your needs.
Defining Callbacks
Og provides a detailed callback facility allowing you to hook into a managed objects Lifecycle. This is a very useful feature that can improve your code considerably. To implement a callback, you have to define one or more of the following methods in your class:
og_pre_insert
og_post_insert
og_pre_update
og_post_update
og_pre_insert_update
og_post_insert_update
self.og_pre_delete
For example, the following code defines a callback for the Post class.
class Post
...
def og_post_insert(conn)
puts 'Hey, a new post was just posted!'
end
end
When post.save is called, you will get this alert:
p = Post.create('Hello')
=> console: Hey, a new post was just posted!
Using OOP techniques
Og managed objects are standard Ruby objects, so we can use class inheritance and module inclusion to minimize the code we have to write. Heres how we can improve the blog schema:
class Category
property :name, String
many_to_many :posts, Post
def initialize(title = nil)
@title = title
end
end
class Common
property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
property :body, String
property :author, String
property :create_time, Time
def initialize(title = nil, body = nil, author = nil)
@title, @body, @author = title, body, author
@create_time = Time.now
end
end
class Post < Common
property :hits, Fixnum, :sql_index => true
has_many :comments, Comment
def initialize(title = nil, body = nil, author = nil)
super
@hits = 0
end
end
class Comment < Common
belongs_to :post, Post
end
In essence, this feature allows you to create SQL tables using inheritance, saving you lots of time when using objects with similar properties. Its also less error prone.
Defining Validation Rules
When managing large amounts of data, enforcing data integrity is important. Og provides another domain specific mini language that allows you to define validation rules in a simple manner. In the following code, the blog schema is enriched with hints that allows Og to automatically generate validation code:
class Common
property :title, String, :sql => 'NOT NULL VARCHAR(32)'
property :body, String
property :author, String
property :create_time, String
validate_value :title
validate_length :body, :range => 2..100, :msg_long => 'argh'
validate_format :author, :format => /[a-z]/, :msg => 'wrong format'
def initialize(title = nil, body = nil, author = nil)
@title, @body, @author = title, body, author
@create_time = Time.now
end
end
This code demonstrates some validations facilities. Using the validate_value macro, we enforce that the title property will have a value. Using the validate_length macro, we enforce the minimum and maximum lengths for the body property. Using the validate_format macro, we enforce a required format for values assigned to the author field.
Lets see this validation in practice:
c = Comment.new
c.valid?
=> false
c.errors.count
=> 3
c.title = 'Hello'
c.valid?
c.errors.count
=> 2
The errors array contains a list of Error objects that point to the offending field and contain a descriptive message.
With Og, you can customize almost everything! More information can be found in the source code (lib/glue/validation.rb). To whet your appetite, here is a list of predefined validation macros:
validate_value
validate_format
validate_length
validate_inclusion
validate_confirmation
TypeMacros If you look at the common class definition, you will notice that the :sql option looks kind of ugly:
:sql => 'VARCHAR2(32) NOT NULL'
When building larger object models, this issue comes up frequently. Og provides a elegant solution in the form of type macros:
def VarChar(size)
return String, :sql => "VARCHAR2(#{size}) NOT NULL"
end
property :title, VarChar(30)
Switching To Another Database
While Postgres is a great database, lets assume that the client wants to switch to MySQL at the last minute. Don't worry, Og can easily accommodate this by simply changing the db reference in the configuration file to look like this and then re-running the example:
db = Og::Database.new(
:database => 'test',
:adapter => 'mysql',
:user => 'postgres',
:password => 'navelrulez'
)
A new MySQL database is automatically created along with all tables, indices, etc. You get all this with changing only one line of code!
Is There More?
You betcha! You can to find more about Og by reading the available RDoc documentation and browsing the examples.
For any questions regarding Og, feel free to ask on the ruby-talk mailing list (which is mirrored to comp.lang.ruby).
A Nitro specific mailing list is also available. You can post questions about Og to this list. Please subscribe to nitro-general@rubyforge.com. The homepage for this list is available here:
https://rubyforge.org/mailman/listinfo/nitro-general
Note that Og is still under heavy development, so new features are being added frequently. Be sure to check back for updates.
Update 2020: Additional discussion:
Rails is not the only web programming framework for Ruby
Update 2018: Resurrected this text from archive.org, grammatical corrections.