Scripting

Scripting Couchstore

There are two kinds of things you can interact with and many things you can do with those. This document provides a reference to these things.

Opening a Database

You get a database handle by calling couch.open(filename). A second, optional boolean argument to couch.open tells it whether or not it's allowed to create a database. If true then a database will be created if it does not already exist.

Example:

local db = couch.open("/tmp/my-new-database.couch", true)

When you're done, db:close() will free up the resources associated with that DB handle.

Interacting with a DB.

Once you have a db object, there are a few things you can do to read or manipulate it.

Storing Data

The db:store is how you get data in. It's got three required arguments and four optional arguments, depending on your usage. In its simplest form:

-- key, value, content_meta
db:save("mykey", "myvalue", 1)

The 1 in this case indicates that this is not a JSON object. The content meta flag allows applications to know what kind of thing is being stored.

If you want to also include revision numbers:

-- key, value, content_meta, rev_seq
db:save("mykey", "myvalue", 1, 842442)

The revision number is something you're expected to have retrieved from a prior call, so if you don't know it, just specify 0.

Also, you can specify the CAS, expiration, and flags meta info:

-- key, value, content_meta, rev_seq, cas, exp, flags
db:save("mykey", "myvalue", 1, 0, 48394839468468364, 1330559793, 6429)

But you can use as much or as little of this as is necessary for your application.

Deleting data

Deleting is similar to storing, except it has one required argument and one optional argument:

-- When you don't care about revno
db:delete("deadkey")

-- When you have a revno
db:delete("deadkey", keyrevno)

Committing

After making a lot of changes, be sure to call db:commit() so that they take effect for future sessions.

Retrieving Data

In the rare case that you want data back, you can use db:get to retrieve it:

local data, docinfo = db:get("mykey")

That gets you the data you stored and a whole lot of metadata that will be discussed below.

There's also a db:get_from_docinfo(docinfo) that allows you to pull a record using exact docinfo (more on this below).

Walking The Changes

You can walk all of the changes that have occurred to the DB using the db:changes function. It takes two arguments: a starting sequence number and a function to call on each change that has occurred since that.

If you don't know what your starting sequence is, it's zero. If you want to poll the store for changes every hour, just remember the last sequence number you had and you can catch up quickly.

Example:

db:changes(0, function(docinfo)
                  print("Found doc with key ``%s''", docinfo:id())
              end)

Using the above-mentioned db:get_from_docinfo(docinfo) function, you can pull the entire record within that loop. You can also issue deletes, whatever you want to do. Have fun.

DocInfo

DocInfo is a structure that represents a bunch of metadata about the document. It includes the document's ID, sequence number, DB sequence number, various meta info (cas, etc...), a flag indicating whether the document has been deleted, size, and location.

There are functions for accessing all these things. Here is an example function you can put in your program that, given a DocInfo will dump out all we know about it:

local function dump_docinfo(docinfo)
   print(string.format("  ID:     %s", docinfo:id()))
   print(string.format("  dbseq:  %d", docinfo:db_seq()))
   print(string.format("  rev:    %d", docinfo:rev()))
   print(string.format("  cas:    %d", docinfo:cas()))
   print(string.format("  exp:    %d", docinfo:exp()))
   print(string.format("  flags:  %d", docinfo:flags()))
   print(string.format("  del:    %d", docinfo:deleted()))
   print(string.format("  cmeta:  %d", docinfo:content_meta()))
   print(string.format("  len:    %d", #docinfo))
end

Local Docs

couchstore also supports local docs. Local docs do not appear in the by_seq index, so you can't discover them through changes or similar. You use them when you want to store some local, private data and you'll look it up again by key.

Storing a Local Document

The db:save_local method is similar to db:save, but more simple. It only takes a key and a value.

db:save_local("mykey", "myvalue")

Retrieving a Local Document

Local documents must be looked up using db:get_local. The namespace is different from "normal" documents.

local value = db:get_local("mykey")

Deleting a Local Document

Local documents may be deleted using the db:delete_local function.

db:delete_local("mykey")