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. The most methods, including those on Client and DB are safe to call concurrently, unless otherwise noted. CouchDB stores JSON, so Kivik translates Go data structures to and from JSON as necessary. The conversion from Go data types to JSON, and vice versa, is handled automatically according to the rules and behavior described in the documentation for the standard library's encoding/json package. Most client and database methods take optional arguments of the type Option. Multiple options may be passed, and latter options take precidence over earlier ones, in case of a conflict. Params and Param can be used to set options that are generally converted to URL query parameters. Different backend drivers may also provide their own unique options with driver-specific effects. Consult your driver's documentation for specifics. 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 HTTPStatus() method, or with a type assertion to `interface { HTTPStatus() 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](]( [![Go Reference](]( [![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 **development** branch of Kivik. The latest stable version
is available [here]( Please
consult the documentation on that page for proper installation of the stable

This branch which will eventually become the Kivik 4.0.0 release. The API is
subject to rapid and unannounced changes at this stage of development. For
production work, you are encouraged to use the latest 3.x release of Kivik,
which is stable. [Read a partial list of breaking changes](#changes-from-3x-to-4x).

Example configuration for common dependency managers follow.

## Go Modules

Kivik 3.x and later supports Go modules, which is the recommended way to use it
for Go version 1.11 or newer. Kivik 4.x only supports Go 1.17 and later. If your project is already using Go modules, simply fetch the desired version:

go get # Stable release
go get # Development release

# Installation

Install Kivik as you normally would for any Go package:

    go get -u

This will install the main Kivik package and the CouchDB database driver. Three officially supported drivers are shipped with this Go module:

  - CouchDB:
  - PouchDB: (requires GopherJS)
  - MockDB:

In addition, there are two partial/experimental drivers available:

  - FilesystemDB:
  - MemoryDB:


Consult the [CLI README]( for full details on the `kivik` CLI tool.

# Example Usage

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

package main

import (

    kivik ""
    _ "" // The CouchDB driver

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

    db := client.DB("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?

I had a number of specific design goals when creating this package:

- Provide a generic database API for a variety of CouchDB-like databases. The previously existing drivers for CouchDB had patchy support for different versions of CouchDB, and different subsets of functionality.
- Work equally well with CouchDB 1.6, 2.x, 3.x, and any future versions, as well as PouchDB.
- Be as Go-idiomatic as possible.
- Be unambiguously open-source. Kivik is released under the Apache license, same as CouchDB and PouchDB.
- Separate out the basic implementation of a database driver (implementing the `kivik/driver` interfaces) vs the implementation of all the user-level types and convenience methods. It ought to be reasonably easy to create a new driver, for testing, mocking, implementing a new backend data storage system, or talking to other CouchDB-like databases.

## 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 4.x aims for full compatibility with all stable releases of Go
  from 1.13. For Go 1.7 or 1.8 you can use [Kivik 1.x](
  For Go 1.9 through 1.12, you can use [Kivik 3.x](
- **CouchDB** The Kivik 4.x CouchDB driver aims for compatibility with all
  stable releases of CouchDB from 2.x.
- **GopherJS** GopherJS always requires the latest stable version of Go, so
  building Kivik with GopherJS has this same requirement.
- **PouchDB** The Kivik 4.x PouchDB driver aims for compatibility with all
  stable releases of PouchDB from 8.0.0.

## What is the development status?

Kivik 4.x is under active development, and subject to radical, and unannounced
API changes. For production use, please use [Kivik 3.x](

## 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?

Kivik is Copyright 2017-2023 by the Kivik contributors, and is released under the
terms of the Apache 2.0 license. See [LICENCE](LICENSE) for the full text of the

### Changes from 3.x to 4.x

This is a partial list of breaking changes between 3.x and 4.x

- Options are no longer a simple `map[string]interface{}`, but are rather functional parameters. In most cases, you can just use `kivik.Param(key, value)`, or `kivik.Params(map[string]interface{}{key: value})` as a replacement. Some shortcuts for common params now exist, and driver-specific options may work differently. Consult the GoDoc.
- The `Authenticate` method has been removed. Authentication is now handled via option parameters.
- The CouchDB, PouchDB, and MockDB drivers, and the experimental FilesystemDB and MemoryDB drivers, have been merged with this repo, rather than behing hosted in separate repos. For v3 you would have imported ``, for example. With v4, you instead use `` for CouchDB, or `` for the experimental FilesystemDB driver.
- The return type for queries has been significantly changed.
  - In 3.x, queries returned a `*Rows` struct. Now they return a `*ResultSet`.
  - The `Offset()`, `TotalRows()`, `UpdateSeq()`, `Warning()` and `Bookmark()` methods have been removed, and replaced with the `ResultMetadata` type which is accessed via the `Metadata()` method. See [issue #552](
  - Calling most methods on `ResultSet` will now work after closing the iterator.
  - The new `ResultSet` type supports multi-query mode, which is triggered by calling `NextResultSet` before `Next`.
  - `Key`, `ID`, `Rev`, `Attachments` all now return row-specific errors, and `ScanKey` may successfully decode while also returning a row-specific error.
- The `Changes` type has been changed to semantically match the `ResultSet` type. Specifically, the `LastSeq()` and `Pending()` methods have been replaced by the `Metadata()` method.
- The `DBUpdates()` and `Changes()` methods now defer errors to the iterator, for easier chaining and consistency with other iterators.
- `DB.BulkDocs()` no longer returns an iterator, but rather an array of all results.
- `Get` now returns a simpler `*Result` type than before.
- `GetMeta` has been replaced with `GetRev`, and no longer claims to return the document size. The document size was never _really_ the document size, rather it is the `Content-Length` field of the HTTP response, which can vary depending on query parameters, making its use for determining document size dubious at best.
- The `StatusCode() int` method on errors has been renamed to `HTTPStatus() int`, to be more descriptive. The related package function `StatusCode(error) int` has also been renamed to `HTTPStatus(error) int` to match.
- `Client.Close()` and `DB.Close()` now block until any relevant calls have returned.
- `Client.Close()` and `DB.Close()` no longer take a `context.Context` value. These operations cannot actually be canceled anyway, by the one driver that uses them (PouchDB); it only stops waiting. It makes more senes to make these functions blocking indefinitely, especially now that they wait for client requests to finish, and let the caller stop waiting if it wants to.

#### CouchDB specific changes

- The `SetTransport` authentication method has been removed, as a duplicate of [couchdb.OptionHTTPClient](
- Options passed to Kivik functions are now functional options, rather than a map of string to empty interface. As such, many of the options have changed. Consult the relevant GoDoc.

#### New features and additions

- Kivik now ships with the `kivik` command line tool (previously part of the `` repository).
- The new [Replicate]( function allows replication between arbitrary databases, such as between CouchDB and a directory structure using the FilesystemDB.

## 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 26 Oct 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