Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Protect your apps from supply chain attacks


Package kivik provides a generic interface to CouchDB or CouchDB-like databases. The kivik package must be used in conjunction with a database driver. The officially supported drivers are: The Filesystem and Memory drivers are also available, but in early stages of development, and so many features do not yet work: The kivik driver system is modeled after the standard library's `sql` and `sql/driver` packages, although the client API is completely different due to the different database models implemented by SQL and NoSQL databases such as CouchDB. 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 according to the rules and behavior described in the documentationf or the standard library's `encoding/json` package ( One would be well-advised to become familiar with using `json` struct field tags ( when working with JSON documents. 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 ahs disconnected, rednering the results of the query irrelevant. To learn more about Go's contexts, read the `context` package documentation ( and read the Go blog post "Go Concurrency Patterns: Context" ( for example code. If in doubt, you can pass `context.TODO()` as the context variable. Example: Kivik returns errors that embed an HTTP status code. In most cases, this is the HTTP status code returned by the server. The embedded HTTP status code may be accessed easily using the StatusCode() method, or with a type assertion to `interface { StatusCode() int }`. Example: Any error that does not conform to this interface will be assumed to represent a http.StatusInternalServerError status code. For common usage, authentication should be as simple as including the authentication credentials in the connection DSN. For example: This will connect to `localhost` on port 5984, using the username `admin` and the password `abc123`. When connecting to CouchDB (as in the above example), this will use cookie auth ( Depending on which driver you use, there may be other ways to authenticate, as well. At the moment, the CouchDB driver is the only official driver which offers additional authentication methods. Please refer to the CouchDB package documentation for details ( With a client handle in hand, you can create a database handle with the DB() method to interact with a specific database.


Version published


[![Build Status](]( [![Codecov](]( [![Go Report Card](]( [![GoDoc](]( [![Website](](

# Kivik

Package kivik provides a common interface to CouchDB or CouchDB-like databases.

The kivik package must be used in conjunction with a database driver.

The kivik driver system is modeled after the standard library's [sql](
and [sql/driver]( packages, although
the client API is completely different due to the different database models
implemented by SQL and NoSQL databases such as CouchDB.

# Versions

You are browsing the **stable v3** branch of Kivik. For the latest changes, you
may be interested in the [development branch](

Example configuration for common dependency managers follow.

## Go Modules

Kivik 3.x is tested against Go 1.13 and later versions, and depends on Go
modules support (added in Go 1.11). If your project does not use modules, and
you are unable to switch, you may use
[Kivik 2.x](

# Installation

Install Kivik as you normally would for any Go package:

    go get -u
    go get -u

This will install the main Kivik package and the CouchDB database driver. See
the [list of Kivik database drivers](
for a complete list of available drivers.

# Example Usage

Please consult the the [package documentation](
for all available API methods, and a complete usage documentation.  And for
additional usage examples, [consult the wiki](

package main

import (

    kivik ""
    _ "" // The CouchDB driver

func main() {
    client, err := kivik.New("couch", "http://localhost:5984/")
    if err != nil {

    db := client.DB(context.TODO(), "animals")

    doc := map[string]interface{}{
        "_id":      "cow",
        "feet":     4,
        "greeting": "moo",

    rev, err := db.Put(context.TODO(), "cow", doc)
    if err != nil {
    fmt.Printf("Cow inserted with revision %s\n", rev)

# Frequently Asked Questions

Nobody has ever asked me any of these questions, so they're probably better called
"Never Asked Questions" or possibly "Imagined Questions."

## Why another CouchDB client API?

Read the [design goals]( for
the general design goals.

Specifically, I was motivated to write Kivik for a few reasons:

1. I was unhappy with any of the existing CouchDB drivers for Go. The [best
one]( had a number of shortcomings:

    - It is no longer actively developed.
    - It [doesn't have an open source license](
    - It doesn't support iterating over result sets, forcing one to load all
      results of a query into memory at once.
    - It [doesn't support CouchDB 2.0](
      sequence IDs or MongoDB-style queries.
    - It doesn't natively support CookieAuth (it does allow a generic Auth method
      which could be used to do this, but I think it's appropriate to put directly
      in the library).

2. I wanted a single client API that worked with both CouchDB and
[PouchDB]( I had previously written
[go-pouchdb](, a GopherJS wrapper around
the PouchDB library with a public API modeled after `fjl/go-couchdb`, but I
still wanted a unified driver infrastructure.

3. I want an unambiguous, open source license. This software is released under
the Apache 2.0 license. See the included file for details.

4. I wanted the ability to mock CouchDB connections for testing. This is possible
with the `sql` / `sql/driver` approach by implementing a mock driver, but was
not possible with any existing CouchDB client libraries. This library makes that
possible for CouchDB apps, too.

5. I wanted a simple, mock CouchDB server I could use for testing. It doesn't
need to be efficient, or support all CouchDB servers, but it should be enough
to test the basic functionality of a PouchDB app, for instance. Kivik aims to
do this with the `kivik serve` command, in the near future.

6. I wanted a toolkit that would make it easy to build a proxy to sit in front
of CouchDB to handle custom authentication or other logic that CouchDB cannot
support natively. Kivik aims to accomplish this in the future.

## What are Kivik's requirements?

Kivik's test suite is automatically run on Linux for every pull request, but
should work on all supported Go architectures. If you find it not working for
your OS/architecture, please submit a bug report.

Below are the compatibility targets for specific runtime and database versions.
If you discover a bug affecting any of these supported environments, please let
me know by submitting a bug report via GitHub.

- **Go** Kivik 3.x aims for full compatibility with all stable releases of Go
  from 1.9. For Go 1.7 or 1.8 you can use [Kivik 1.x](
- **CouchDB** The Kivik 3.x CouchDB driver aims for compatibility with all
  stable releases of CouchDB from 1.6.1.
- **GopherJS** GopherJS always requires the latest stable version of Go, so
  building Kivik with GopherJS has this same requirement.
- **PouchDB** The Kivik 3.x PouchDB driver aims for compatibility with all
  stable releases of PouchDB from 6.0.0.

## What is the development status?

Kivik 3.x is considered production-ready and comes with a complete client API
client and backend drivers for CouchDB and PouchDB.

Future goals are to flesh out the Memory driver, which will make automated
testing without a real CouchDB server easier. Then I will work on completing
the 'serve' mode.

You can see a complete overview of the current status on the
[Compatibility chart](

## Why the name "Kivik"?

[Kivik]( is a line
of sofas (couches) from IKEA. And in the spirit of IKEA, and build-your-own
furniture, Kivik aims to allow you to "build your own" CouchDB client, server,
and proxy applications.

## What license is Kivik released under?

This software is released under the terms of the Apache 2.0 license. See, or read the [full license](

## What projects currently use Kivik?

If your project uses Kivik, and you'd like to be added to this list, create an
issue or submit a pull request.

- [Cayley]( is an open-source graph
  database. It uses Kivik for the CouchDB and PouchDB storage backends.


Last updated on 30 Mar 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc