To set up Xeround, sign up for an account and set up a database instance in the AWS U. S. East region. Go to the page for the database instance, and you will see the username and the database URLs.

Rails reads its database configuration from config/database.yml. Heroku overwrites config/database.yml with a file it generates from the DATABASE_URL configuration variable. The configuration variable uses the database driver name as the network scheme (e. g. mysql://). There is more than one mysql driver for Rails; the one suggested in the Rails Guide is mysql2.

To use mysql2 as the database driver with Xeround, use the following for the DATABASE_URL configuration variable:

heroku config:add DATABASE_URL='mysql2://{{username}}:{{password}}@{{hostname}}:{{port}}/{{dbname}}'

1

heroku config:add DATABASE_URL='mysql2://{{username}}:{{password}}@{{hostname}}:{{port}}/{{dbname}}'

The username, hostname, and port number can be seen on the DB Instance Manager page on Xeround. The hostname and port are under one of the three DNS Names; I picked the top one. The password is what was entered for the database password during signup. The database name is the name of the database to be added using PHPMyAdmin.

The driver also needs to be included in the Gemfile. To include it just for production, use:

group :production do
  gem 'mysql2'
end

After adding this, run bundle install, commit your changes, and push to Heroku.

The database still needs to be created. To create the database, click on one of the links under DNS Names on the DB Instance Manager. This brings up PHPMyAdmin. Enter the database password and log in. Then create the database, with the same name used for the DATABASE_URL configuration variable.

Now that the database has been created, the DATABASE_URL is set, and the Gemfile is updated and pushed, you should be able to migrate the database by running heroku run rake db:migrate.

I’m using the latest version of Rails (3.1.1) on Heroku’s cedar stack.

It will be interesting to see how well Xeround works for this project. There are other MySQL hosting options for EC2 if I need them, and migrating is fairly simple.

Getting Started

The first thing I tried was creating a merb project with a single page referencing jQuery, and accessing CouchDB from there. The browser’s security model got in my way, however. A page on one port on localhost can’t access another port with AJAX. I searched for ways to give a page special permission, but my search turned up empty and I figured that I’d rather not go against the browser anyway, if I could help it.

The next thing I tried was getting a page that references jQuery to be served by CouchDB’s web server. That way the page and jQuery’s JSON API would be on the same port and Firefox would be happy. I opened up CouchDB’s Futon Utility Client at http://localhost:5984/_utils/ and found that it already had the latest version of jQuery included! Problem solved.

I opened the FireBug console (which was already enabled on localhost from when I was trying to get it working with my Merb project) and started trying out jQuery’s AJAX functions on CouchDB.

The GET request returned successfully! However, FireBug doesn’t retain the response, so I have to click Load Response to get it.

OK, there’s CouchDB’s welcome message! Expanding the GET request and clicking Load Response is tedious, though, so a better technique is needed. The first thing that comes to mind is doing a synchronous request. I find that get() doesn’t support this option, so I need to use ajax().

Aside from FireBug’s quoting FAIL, it works nicely. What I’d really like, though, is for FireBug to pretty-print the JSON. So I throw an eval() statement around it, and add the left side of an assignment statement because otherwise I would get an error (another way to get it working is to throw square brackets around the expression).

The output is quite a bit nicer, in my opinion.

Creating a Database

To create a database I use the HttpDatabaseApi page on the CouchDB wiki. Creating a database requires use of a PUT request, which can be made with jQuery’s ajax() function if the browser supports it (and Firefox does).

CouchDB returns a simple OK message to let me know it worked.

Creating a Document

Now that I have a database, I can create a document using the HttpDocumentApi. I opt to take the cavalier approach of having the server generate an ID rather than supplying an ID of my own. To do this, I send a POST with the database’s URL for the address and the document’s contents for the POST data. To send the POST data, I call ajax() with the document’s contents (as a JSON expression) for the data option and the string ‘json’ for the dataType option.

It didn’t work. I expand the POST and look at the data sent to find out why.

The ajax() function didn’t serialize the data! It’s not built into jQuery. It makes sense, given that one of jQuery’s features is its small footprint. I remember that when I viewed the source of the main page of CouchDB’s Futon Utility Client I saw a JSON include. It’s in http://localhost:5984/_utils/script/json2.js. It’s not a jQuery plug-in, but its interface is fairly simple. To serialize data, you call JSON.stringify() with an object as the first parameter. I add this to my statement and try again.

It worked! Or, at least, it didn’t error. It returned a globally unique ID (GUID) generated by the server. Now I use the ID to GET the document’s contents.

Only a summary of the object is shown. If I click the object it expands to a full view.

The data is there. The revision number is also present. One of CouchDB’s coolest features is built-in versioning.

After I realized that I was given only a summary of the object, I tried creating a document again and seeing if I missed any info that was supplied in the response to the POST request. It turns out that I did. The revision (_rev) was given. I’d like to have Firebug print out the whole response (and not a short summary), but I don’t see any way of doing so.

Updating a Document

Documents can be updated by sending a PUT request with the document’s URL as the address and the new contents as the data. The new contents must include the revision number upon which the update is based. This is to prevent conflicts. If a revision number other than that of the latest revision is supplied, it means that another client updated it first.

I update the document by getting the latest copy, storing it in a variable, removing the ID (since it’s already in the URL), changing the radius, and sending a PUT request with the new database contents.

The document is updated. If I expand the object I can see the new revision number.

Pretty cool, huh?

Conclusion & Next Steps

Before I tried using CouchDB with Firebug, I tried using the Futon Utility Client. I felt that I learned more and better retained what I learned when I used Firebug. Firebug as it is right now has a couple of issues that will keep me from using it as an environment in which to try doing different things with CouchDB. The first issue is that the pretty-print doesn’t show the full object in the console view, and there’s no option in the UI to make it do so. The second issue is that I find the editor to be insufficient. When the editor is in vertical mode, there’s no way to go through the history of commands entered. When the editor is in horizontal mode, it can’t expand beyond one line. When I switch between tabs, the text in the editor is often lost.

Firebug is, however, being actively worked on, and will hopefully get some features that will make it easier and more fun to use to play with JavaScript API’s and web services.

I would like to get the custom JavaScript environment mentioned at the top of this post set up and working with CouchDB. One way to get it working might be to set up a proxy of sorts to CouchDB. I could have any requests starting with /couchdb be forwarded to the CouchDB port with the /couchdb part stripped off.

This was fun. I think the next thing I’ll do with CouchDB is try writing a simple wiki using CouchDB and Merb.

]]> http://benatkin.com/2008/09/13/trying-out-couchdb-in-firebug/feed/ 5