Skip to content
Jonathan Hall edited this page Apr 30, 2017 · 2 revisions

Welcome to the Kivik wiki, a collection of documentation about the Kivik CouchDB tool set.


This section provides an overview of concepts relevant to the general use of Kivik. For specific coding examples, consult the Usage Examples.

Working with JSON

CouchDB stores JSON, so Kivik translates Go data structures to and from JSON as necessary. The conversion between Go data types and JSON, and vice versa, is handled automatically by according to the rules and behavior described in the documentation for the encoding/json package.

One would be well-advised to become familiar with using json struct field tags when working with JSON documents.

Using contexts

Most Kivik methods take context.Context as their first argument. This allows the cancellation of blocking operations in the case that the result is no longer needed. A typical use case for a web application would be to cancel a Kivik request if the remote HTTP client has disconnected, rendering the results of the query irrelevant.

func myHandler(w http.ResponseWriter, r *http.Request) {
    ctx : r.Context() // Fetch the context from the request. It will be canceled
                      // if the HTTP client disconnects before it receives a
                      // response.
    row, err := db.Get(r.Context(), "cow")
    if err != nil {
        if ctx.Err() != nil {
            // Context was canceled, nothing to do
    var cow Animal
    if err = row.Scan(&cow); err != nil {

To learn more about Contexts, be sure to read the context package documentation and see see the Go blog for example code for a server that uses Contexts.

If in doubt, you can pass context.TODO() as the context variable. Think of the TODO context as a place-holder for cases when it is unclear which Context to use, or when surrounding functions have not yet been extended to support a Context parameter.

For example:

client, err := kivik.New(context.TODO(), "couch", "http://localhost:5984/")

Error handling

Kivik returns errors which conform to the statusCoder interface. This interface is not exported by the package, but is part of the stable public API.

type statusCoder interface {
    StatusCode() int

This allows access to Kivik-generated errors which embed the HTTP status code returned by the server (or in some cases, where an HTTP request wasn't actually made, the equivalent meaning). Access to this status code is possible via the StatusCode() method:

row, err := db.Get(context.TODO(), "my_doc_id")
switch kivik.StatusCode(err) {
case kivik.StatusNotFound:
case kivik.StatusUnauthorized:
    panic("Authentication required")
case kivik.StatusForbidden:
    panic("You are not authorized")
    return err

Driver authors are expected to return errors that conform to the statusCoder interface. Any error that does not conform to this interface will be assumed to represent a kivik.StatusInternalServerError status code.

You can’t perform that action at this time.