Clone this wiki locally
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
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.
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.
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)
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
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 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)
After making a lot of changes, be sure to call
db:commit() so that
they take effect for future sessions.
In the rare case that you want data back, you can use
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
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.
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 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
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
couchstore also supports local docs. Local docs do not appear in the
by_seq index, so you can't discover them through
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
db:save_local method is similar to
db:save, but more simple.
It only takes a key and a value.
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