Ruby on Rails on NuoDB

In addition to working on the core NuoDB Database, we’ve been hard at work writing drivers to help you use NuoDB with your favorite languages and frameworks. In this post I’m going to walk you through getting stared with our Ruby driver andActiveRecord adapter. Together, these two ruby gems make it really easy to get going with Ruby on Rails and NuoDB.

Specifically, I’m going to go through the steps to

• Install NuoDB
• Install the NuoDB Ruby driver and ActiveRecord adapter
• Start your NuoDB database
• Configure your application

For this example I am going to be creating a simple “blog” application that has users, posts and comments. If you want to follow along exactly, you can create it by running

rails new blog
cd blog/

or you can adapt the steps to your own existing application.

To get started, download NuoDB for your platform. Currently NuoDB is supported on Linux, Mac OSX, and Windows, but our Ruby driver requires either Linux or Mac OSX. If you install the Mac .pkg or the Linux .deb or .rpm the installer will take care of setting up everything that you need.

To use NuoDB with Rails you need two gems: the NuoDB Ruby driver and the NuoDB ActiveRecord adapter. The NuoDB Ruby driver provides bindings for interacting with NuoDB from Ruby. The two primary pieces that you get from the NuoDB ruby driver are the ability to easily issue SQL queries from within a ruby program and the ability to convert the responses into types that ruby understands.

The NuoDB ruby driver can be used entirely on it’s own, without Rails or any other ruby gems (there is an example of how you could do that on its github page), but what really makes it useful in a Rails application is the NuoDB ActiveRecord adapter. The adapter allows the ActiveRecord ORM to work with NuoDB so that you can work with model objects rather than raw SQL. This also means that as long as you aren’t using any language specific raw SQL in your Rails application, it will work with NuoDB without any code changes.

To install both gems, add the following to your Gemfile:

gem 'activerecord-nuodb-adapter'

and run

bundle install

Bundler will take care of the dependency and install both gems.

One difference between NuoDB and some other databases that you may have used is how you start up a database. A NuoDB database is just a collection of processes running on one or more hosts. This architecture makes it really easy to scale out a NuoDB database, but it means that the rake db:create command would require a lot more input (how many processes should start, which hosts should they be running on, what sort of archive should they be using, etc.). We’re currently working on some tools to make it easier to describe exactly what sort of database you want, but for now you need to start the database manually.

You can do this using the command line NuoDB Manager or through the webconsole. For this example I’m going to use the Manager to start up the simplest usable NuoDB database: one Storage Manager process archiving to local disk and one Transaction Engine process, all on a single host. Start the manager by running

java -jar /opt/nuodb/jar/nuodbmanager.jar --broker localhost --user domain --password bird

(If you installed to a nonstandard location or updated the domain credentials you will need to change the command accordingly)

In the Manager prompt run

start process sm host localhost database blog_development archive /var/opt/nuodb/production-archives/blog_development initialize yes options ''

to start a Storage Manager and

start process te host localhost database blog_development options '--dba-user dba --dba-password passw0rd'

to start a Transaction Engine. You now have a running NuoDB database! If you want you could also start up blog_test and blog_production databases at this point. Just make sure to update the database name and archive directory. For more information on running databases from the command line check out Getting Started: Running a Database. When you’re done, quit the Manager with the command

exit

Now that we have a NuoDB database running, we can tell Rails about it. Update yourconfig/database.yml to

development:
  adapter: nuodb
  database: blog_development@localhost
  username: dba
  password: passw0rd
  schema: blog

The database: value is of the format [DATABASE_NAME]@[NUODB_BROKER_HOST]. The NuoDB installer launches a broker on the localhost by default, and we choseblog_development as the database name, so in this case we useblog_development@localhost.

The username: and password: are the dba-user and dba-password specified in thestart process te Manager command. If you chose different dba credentials you should use them here as well.

Finally the schema: tells Rails which NuoDB schema should contain the tables. You don’t need to explicitly create the schema first; if it already exists NuoDB will use it, and if it does not NuoDB will create it.

From here on out everything is the same as it would be with any other database.

Generate your models

rails generate model user name:string email:string
rails generate model post user_id:integer title:string body:text
rails generate model comment user_id:integer post_id:integer body:text

and migrate the database

rake db:migrate

Next add relations to the models in: app/models/user.rb

class User < ActiveRecord::Base
  attr_accessible :email, :name
  has_many :posts
  has_many :comments
end

app/models/post.rb

class Post < ActiveRecord::Base
  attr_accessible :body, :title, :user_id
  belongs_to :user
  has_many :comments
end

app/models/comment.rb

class Comment < ActiveRecord::Base
  attr_accessible :body, :post_id, :user_id
  belongs_to :user
  belongs_to :post
end

Now we can check out our models by starting up the rails console with

rails console

Create a user with

u = User.create(:name => "John Smith", :email => "[email protected]")

and you should see some messages from NuoDB like

(0.1ms)  begin transaction
(0.2ms)  commit transaction

Now we can create a post and some comments

p = u.posts.build(:title => 'My Post', :body => "This is my first post! Isn't it awesome?")
p.comments.build(:body => "Wow, great post!", :user_id => u.id)
p.comments.build(:body => "Isn't commenting on your own post a little weird?", :user_id => u.id)
p.save!

To see that everything worked as expected, try

Post.last.comments

And you will see something like

Post Load (2.0ms)  SELECT `posts`.* FROM `posts` ORDER BY `posts`.`id` DESC FETCH FIRST 1 ROWS ONLY
Comment Load (1.3ms)  SELECT `comments`.* FROM `comments` WHERE `comments`.`post_id` = 3
=> [#<Comment id: 3, user_id: 1, post_id: 3, body: "Wow, great post!", created_at: "2013-05-31 14:17:11", updated_at: "2013-05-31 14:17:11">, #<Comment id: 4, user_id: 1, post_id: 3, body: "Isn't commenting on your own post a little weird?", created_at: "2013-05-31 14:17:11", updated_at: "2013-05-31 14:17:11">]

As you can see, after a bit of initial configuration using NuoDB with Ruby on Rails is no different than any other backing database. This means that you can easily port an existing app or write a new one to take advantage of NuoDB’s elastic scalability and transactional consistency.

Obviously this “blog” isn’t really an application yet; all we built was the MVC “M”. If you want to see a complete NuoDB backed Rails application, check out NuoKeg on Github(blog post forthcoming, but until then you can follow NuoKeg on twitter). Try Ruby on Rails on NuoDB and let us know how it goes!