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 and ActiveRecord 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
Step 0 – Create 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.
Step 1 – Installing NuoDB
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.
Step 2 – Installing Gems
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:
Bundler will take care of the dependency and install both gems.
Step 3 – Start the database(es)
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
Step 4 – Configure your application
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.
Step 5 – Build your app
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
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
class Post < ActiveRecord::Base attr_accessible :body, :title, :user_id belongs_to :user has_many :comments end
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
Create a user with
u = User.create(:name => "John Smith", :email => "firstname.lastname@example.org")
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
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!