This tutorial is meant to get you up and running with ColdFusion and CouchDB. If you have never heard about CouchDB i suggest you read Matt Woodward's slighty chaotic but very informative article about CouchDB.

Step 1: Getting a CouchDB instance up and running

Currently (as of version 0.10) CouchDB is available for Linux and Mac. If you are running Linux, you might know how to get it up and running. If you got a Mac available (either your own or in your network) then things are very easy. Just download CouchDBX and you are ready to go in 1 minute.

After you started CouchDB you will see the administration interface called Futon. If you want to reach your CouchDB from another server, you will have to change the IP address on which CouchDB listens to requests:

Set the bind_address to 0.0.0.0 to make it listen to all requests or set it to the IP of that machine (e.g. 192.168.120.120) so it can only be reached within your network. If you leave it to the default (127.0.0.1) you will have a hard time reaching CouchDB through the network.

Step 2: Test your connection from ColdFusion to CouchDB

Create a test.cfm file and drop in the following lines:

<cfscript> Request.Couch.Server="http://192.168.11.97"; // set this to the IP of your CouchDB machine Request.Couch.Port="5984"; </cfscript> <cfhttp url="#Request.Couch.Server#/" port="#Request.Couch.Port#" method="GET"></cfhttp> <cfset Variables.CDBR=DeserializeJSON(cfhttp.FileContent)> <cfdump var="#Variables.CDBR#">

If all goes well you should see this:

Step 3: Creating a database in CouchDB

Step 4: Inserting (PUT/POST) data into your new CouchDB

First of all - you should have read about this already - but i just want to say it again.
CouchDB is different from your SQL database:

• There are no tables. All data is stored in docs (documents). What you save in those documents is up to you.
• There is no database schema - which means you can save any data you want without CouchDB complaining about fields values or wrong data formats
• Everything is http and JSON. This is good - and you will now see why.

Let's say you want to save some address data which your ColdFusion application happens to receive via an Ajax Request in the format

{ "recipe": "Spaghetti Bolognese", "skill": "easy", "ingredients": ["pasta","salt","pepper","tomatoes","ground beef","onions"] }

When you receive data like in the form variable FORM.recipe this you will usually do a DeserializeJSON so you can work with the data in CF:

<cfscript> content=DeserializeJSON(FORM.recipe)> /* we just created a struct with the following elements: content.recipe, content.skill, content.ingredients The cool thing: content.ingredients will already be an array. So content.ingredients[2] is "salt". now we can use this data */ if (content.skill EQ "easy") // do something... </cfscript>

To save this content struct to CouchDB you simply do a cfhttp request like this

<!--- replace the ip and port with your settings ---> <cfhttp url="192.168.123.45" port="5984" action="post"> <cfhttpparam type="header" name="Content-Type" value="application/json"> <cfhttpparam type="body" value="#SerializeJSON(content)#"> </cfhttp>

Is it really that easy? And where is CFQUERY?

Yes. It is that easy. Let's take a look at what happens here:

• We send this the body in a POST request to the CouchDB server.
  The method (POST) tells CouchDB that we want to save this data. As we specify no id this will be an insert and CouchDB will generate an id for the record.
• The body will contain the JSON string that i showed above. SerializeJSON will create this from the content struct that we created with DeserializeJSON before. Yes - i know - there is no need to deserialize and serialize if we don't change the data. But usually your app will add something to your data so i used this example.

In CouchDB you should now have a new doc like this:

{ "_id": "f4c1889db42fcb3ad0d531a478e58745", "_rev": "1-ab5483bbf49bb4b292ff788190cb9fc6", "recipe": "Spaghetti Bolognese", "skill": "easy", "ingredients": [ "pasta", "salt", "pepper", "tomatoes", "ground beef", "onions" ] }

To be continued...