$ gem install rid

$ rid

Overview

CouchDB is a document based database with REST HTTP interface. It has built in support for map/reduce views, attachments, validation, routing and much more.

One of CouchDBs core feature is replication. CouchDB comes with a replication API wich makes it trival to synchronize databases, even in continous mode.

For further information read the free book CouchDB: The Definitive Guide by J. Chris Anderson, Jan Lehnardt and Noah Slater.

You can create database backed web applications using only CouchDB. They are called CouchApps.

CouchApps

CouchApps are JavaScript and HTML5 applications served directly from CouchDB. If you can fit your application into those constraints, then you get CouchDB's scalability and flexibility "for free" (and deploying your app is as simple as replicating it to the production server).
[http://couchapp.org]

Read more about CouchApps on the couchapp page.

Rid

Because CouchApps live inside CouchDB design documents, they need to be JSON documents.

Rid maps those JSON documents to the filesystem, where a filename reflects a JSON key and its contents the value.

Having the JSON structure on your disk you can easily code them using your favorite editor. Once you are done Rid can push your project to the database.

Gems

For extendability Rids commands are each extra gems. The rid gem is a core package which requires the following commands:

rid init

Create application directory structure

rid dd

Create design document directory structure

rid fn

Create CouchDB functions

rid push

Push application to CouchDB

rid export

Export application as JSON

Rid gems are easy to build. You just have to follow some naming conventions and your command will appear automatically once installed.
More Rid gems and informations about writing Rid gems come soon.

Installation

Lets describe how to get Ruby, a CouchDB and Rid.

Installation of Ruby

Rid is written in Ruby. So you need a Ruby environment. On Debian like Linux distrubutions you can install Ruby and friends via apt:

# apt-get install ruby rake rubygems

If you're developing on Mac OS X, all prerequisites are met. For other platforms, refer to the Ruby website.

Note that you do not need Ruby and Rid on the server which is running CouchDB! Once Deployed, Rid applications are served completely standalone by CouchDB.

Get a Couch

You can install CouchDB, eg with apt:

# apt-get install couchdb

Or you can get your free beta CouchDB at Couch.io.

Install Rid

Rid is shipped as a RubyGem. Therefore the installation of Rid is as easy as typing three words:

$ gem install rid

Explore more Rid commands

Each Rid command is a different gem, so its easy to extend Rid. You can list the available rid commands via:

$ gem list --remote rid-

Getting started with Rid

In this tutorial we will create a little todo list application with Rid.

Prerequisites

Be sure you have Rid installed and a running CouchDB. If your CouchDB is not in admin party mode keep your access data handy.

Starting the project

Change to a directory, which will contain your Rid projects, eg ~/rid, and

$ rid init todo
create  _database
create  README

This will create a new directory ./todo.

$ cd todo
$ ls
_database  README

Look at the _database file. It holds the complete url to your database.

$ cd cat _database 
http://127.0.0.1:5984/todo

There is one database per project, but you can use the same database for many projects. You are not limited to one database per project if you use replication or sequencially push to many databases. More on this topic later.
Per default Rid will setup a database on the local maschine, using the underscored filename you choosed, in this case todo. You can change this file whenever you want.

Maybe you do not have a local couch running and you may want to specify the database:

rid init todo -d http://username:password@couch.example.com/my_database

Rid will write the proper database config file. As you can see the url can contain authentification informations.

Find out more options via

$ rid help init

Hello World!

Lets create a simple document. Make sure you are inside the application root directory, in my case ~/rid/todo.

$ mkdir mydoc
$ echo "mydoc" > mydoc/_id
$ echo "Hello World" > mydoc/title

And push it, baby!

$ rid push
        push  mydoc: {"ok":true,"id":"mydoc","rev":"1-feb3d394b2a30b1c8b4ab029ddec8a0c"}

We just created the database, because it did not exist yet, and a document with the id mydoc. Lets look at this new document:

$ curl http://127.0.0.1:5984/todo/mydoc
{"_id":"mydoc","_rev":"1-feb3d394b2a30b1c8b4ab029ddec8a0c","title":"Hello World"}

You see the JSON representation of mydoc. You can also look at this document with your browser, just open http://127.0.0.1:5984/todo/mydoc.

Each CouchDB document has an _id and a _rev attribute. The ID cannot be changed, once created. The revision is generated by CouchDB on each document update. The revision is prefixed by an update count which increments on each document change.

We now will say hello with HTML. To do this, we will create an attachment, which holds the HTML code. Again, ensure that you are inside the root directory.

$ mkdir mydoc/_attachments
$ echo "<h1>Hello World</h1>" > mydoc/_attachments/hello_world.html
$ rid push
        push  mydoc: {"ok":true,"id":"mydoc","rev":"2-379a31cac5b8d3a46165b12c89fbcc9b"}

Now open http://127.0.0.1:5984/todo/mydoc/hello_world.html and pay back to the HTML.

Thats fine. Now we look at how we can display the title of the mydoc document as HTML.

Transforming documents with show functions

The previous hello from mydoc does not look like Hello World. Lets get rid of the JSON and convert it to html. We can do this using a show function.

Show functions are defined inside design documents. Design documents are special documents which holds application logic.

Go on creating a design document. We could do so manually again but let Rid help:

$ rid dd hello
      create  hello/_id

If you look at the file hello/_id, you'll see that Rid wrote _design/hello. Design document IDs must start with _design/.

Now its time to create our CouchDB show function. Rid can generate function skeletons:

$ rid fn show hello world
      create  hello/shows/world.js

The empty show function looks like

function(doc, req) {
}

A show function gets invoked by passing the document, if found, and a request object.

Lets change the script to return a HTML fragment:

function(doc, req) {
  return '<h1>Hello from show function!</h1>';
}

and push our design document to CouchDB

$ rid push
   unchanged  mydoc: {"rev":"2-379a31cac5b8d3a46165b12c89fbcc9b"}
        push  _design/hello: {"ok":true,"id":"_design/hello","rev":"1-524ac4e1b22a392d1cf79e0b10d753b8"}

Now point your browser to http://127.0.0.1:5984/todo/_design/hello/_show/world and enjoy.

Wait. We are not ready by now. We should change the show function to include the documents value

function(doc, req) {
  doc = doc || {};

  return '<h1>Show function: ' + doc.title + ' </h1>';
}

And push. http://127.0.0.1:5984/todo/_design/hello/_show/world/mydoc will fetch the title attribute from the document with ID mydoc and sends it to you as html.

What we have done

We now know how to create a new project with rid init, create documents manually or with the help of rid dd. We generated a show function with rid fn, which generates a HTML representation of our document.

Help

Every command has a help. For example try rid help push to get information about rid push usage and options.

Those help pages are also online if you are curious:

• rid
• rid-init
• rid-dd
• rid-fn
• rid-push
• rid-export

Please feel free to write an email to schmidt@netzmerk.com if you have further questions or suggestions.

  NAME:

    Rid: Rest in development.

  DESCRIPTION:

    Rid is a toolkit to relax in web development.

    Based on CouchDB you get a distributed,
    high scaling web application infrastructure with Rid.
    
    Rid commands are distributed as RubyGems. Explore more Rid commands via
    'gem list --remote rid-'
    
    Type 'rid help command'
    to get information about each command.


  COMMANDS:
        
    dd                   Generate design document with Rid dd.          
    export               Export project as JSON.                
    help                 Display global or [command] help documentation.                
    init                 Generate project files.                
    push                 Deploy project.        

  GLOBAL OPTIONS:
        
    -q, --quiet 
        Supress status output
        
    -b BEHAVIOR, --behavior BEHAVIOR 
        Can be skip, pretend and force
        
    -h, --help 
        Display help documentation
        
    -v, --version 
        Display version information
        
    -t, --trace 
        Display backtrace when an error occurs
      

  NAME:

    init

  DESCRIPTION:

    Generate project files.

  SYNOPSIS:

    rid init [ROOT]

  EXAMPLES:
        
    # Init a Rid project myapp
    rid init myapp
        
    # Init at ~/rid/myapp
    rid init ~/rid/myapp
        
    # Init with database set to example.com/myapp
    rid init -d example.com/myapp
        
  OPTIONS:
        
    -d DATABASE, --database DATABASE 
        Setup database url
      

  NAME:

    dd

  DESCRIPTION:

    Generate design document with Rid dd.

  SYNOPSIS:

    rid dd NAME

  EXAMPLES:
        
    # Generates design document myapp
    rid dd myapp
        
  OPTIONS:
        
    -r ROOT, --root ROOT 
        Setup application root
      

  NAME:

    fn

  DESCRIPTION:

    Generate design document with Rid dd.

  SYNOPSIS:

    rid fn TYPE DOC [NAME]

  EXAMPLES:
        
    # Generates show function "post" inside document "post"
    rid fn show post
        
    # Generates show function "myshow" inside document "mydoc"
    rid fn show mydoc myshow
        
  OPTIONS:
        
    -r ROOT, --root ROOT 
        Setup application root
      

  NAME:

    push

  DESCRIPTION:

    Deploy project.

  SYNOPSIS:

    rid push

  EXAMPLES:
        
    # Deploy a Rid application
    rid push
        
    # Deploy to example.com/myapp database
    rid push -d http://example.com/myapp
        
    # Force deployment to example.com/myapp database
    rid push -d http://example.com/myapp -f
        
    # Deploy from ~/rid/myapp to example.com/myapp
    rid push -r ~/rid/myapp -d http://example.com/myapp
        
  OPTIONS:
        
    -d DATABASE, --database DATABASE 
        Setup database url
        
    -r ROOT, --root ROOT 
        Setup application root
        
    -f, --force 
        Do not care about _rev
      

  NAME:

    export

  DESCRIPTION:

    Export project as JSON.

  SYNOPSIS:

    rid export

  EXAMPLES:
        
    # Export a Rid application
    rid export
        
    # Export from ~/rid/myapp
    rid export -d ~/rid/myapp
        
    # Export application without attachments
    rid export --exclude-attachments
        
  OPTIONS:
        
    -r ROOT, --root ROOT 
        Setup application root
        
    --exclude-attachments 
        Exclude attachments (default is false)