I've recently started hacking on a small single-page app to try and get on top of the wonderful Sammy JavaScript framework. A natural fit for storing data is CouchDB, which I also have no prior experience with, so I needed to also jump into that. Since it talks HTTP and JSON it's very easy to get started with: I threw together this quick cheatsheet for making CRUD operations to CouchDB with curl. This is basically just my quick notes, the short version of the HTTP API docs, which are obviously more thorough.
Install
Installation is easy: sudo aptitude install couchdb (or brew install couchdb). You can verify that worked by visiting Futon, the web-based interface that ships with Couch, at http://localhost:5984/_utils. But of course we want to use curl here, so:
curl http://localhost:5984/
==> {"couchdb":"Welcome","version":"1.0.1"}
Simple CRUD operations
Create a database:
curl -X PUT http://localhost:5984/testdb
==> {"ok": true}
curl -X PUT http://localhost:5984/testdb
==> {"error":"file_exists","reason":"The database could not be created, the file already exists."}
Add a document with a POST request. Couchdb will automatically create a UUID for you:
curl -X POST http://localhost:5984/testdb -d '{"name": "Dieter"}' -H "Content-Type: application/json"
==> {"ok":true,"id":"4f761d4dc3b4d602ffdc2be02600140b","rev":"1-40b62334f3dc02ca64532fbec03f3a35"}
Or, to do a PUT request, you need to provide a UUID yourself (ie, make one in your application):
curl -X PUT http://localhost:5984/testdb/youruuid -d '{"name": "Joe"}' -H "Content-Type: application/json"
Either way, use that UUID to read the document:
curl -X GET http://localhost:5984/testdb/4f761d4dc3b4d602ffdc2be02600140b
==> {"_id":"4f761d4dc3b4d602ffdc2be02600140b","_rev":"1-40b62334f3dc02ca64532fbec03f3a35","name":"Dieter"}
You can also read all documents with the special:
curl -X GET http://localhost:5984/testdb/_all_docs
==> {"total_rows":1,"offset":0,"rows":[{"id":"4f761d4dc3b4d602ffdc2be02600140b","key":"4f761d4dc3b4d602ffdc2be02600140b","value":{"rev":"1-40b62334f3dc02ca64532fbec03f3a35"}}]}
Couchdb stores versions of documents, so to edit one, you need to provide the revision as well:
curl -X PUT http://localhost/couchdb/testdb/4f761d4dc3b4d602ffdc2be02600140b -d '{"_id":"4f761d4dc3b4d602ffdc2be02600140b","_rev":"1-40b62334f3dc02ca64532fbec03f3a35","name":"Dieter Limeback"}'
==> {"ok":true,"id":"4f761d4dc3b4d602ffdc2be02600140b","rev":"2-5fc171bc10cb2c7cff75741dff04fa0d"}
...unless what's currently in the db doesn't match what you're doing (ie, you're trying to edit an old revision) at which point you'll see:
{"error":"conflict","reason":"Document update conflict."}
To delete, you pass the rev as a parameter:
curl -X DELETE http://localhost:5984/testdb/4f761d4dc3b4d602ffdc2be02600140b?rev=2-5fc171bc10cb2c7cff75741dff04fa0d
==> {"ok":true,"id":"4f761d4dc3b4d602ffdc2be02600140b","rev":"3-7b5d2673af36e2fd42b7f356b9bc6c7b"}
which looks weird, since it looks like it created a new revision, except if you try to GET it again:
curl -X GET http://localhost:5984/testdb/4f761d4dc3b4d602ffdc2be0260014b0
==> {"error":"not_found","reason":"deleted"}
Delete the entire db with:
curl -X DELETE http://localhost:5984/testdb
==> {"ok":true}
That's it for now; nothing too crazy. If I end up making similar notes when learning about Couch views I'll be sure to post them as well.