Skip to content
Kivik provides a common interface to CouchDB or CouchDB-like databases for Go and GopherJS.
Branch: master
Clone or download
flimzy Merge pull request #397 from go-kivik/rdstream
Convert RevsDiff to a stream producer
Latest commit 192e688 Jun 25, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc Update paths Dec 14, 2017
driver Convert RevsDiff to a stream producer Jun 25, 2019
errors Ignore some goconst warnings in test files Apr 2, 2019
mock Convert RevsDiff to a stream producer Jun 25, 2019
testdata Add _revs_diff support Jun 21, 2019
travis
.codecov.yml Remove old drivers Dec 10, 2017
.gitignore Remove kivik server files Oct 25, 2017
.golangci.toml Use new linter Apr 2, 2019
.travis.yml Test against CouchDB 2.3 Jun 5, 2019
CONTRIBUTING.md Add a CONTRIBUTING.md document Jul 30, 2017
ISSUE_TEMPLATE.md Update Go compatibility documentation Dec 15, 2017
LICENSE.md Add README and license Feb 11, 2017
Makefile Add PouchDB support for CreateIndex Apr 14, 2017
README.md Update README to show documentation for the devel branch May 9, 2019
attachments.go Delint: shorter code Apr 2, 2019
attachments_test.go
bulk.go Change BulkDocs to accept a slice, rather than depending on reflection Feb 13, 2019
bulk_test.go Ignore some goconst warnings in test files Apr 2, 2019
changes.go Add Changes ETag support Jun 5, 2019
changes_test.go Add Changes ETag support Jun 5, 2019
cluster.go Update a bunch of errors to use Message: instead of Err: errors.New(...) Jun 6, 2019
cluster_test.go Add support for the /_cluster_setup endpoint Feb 1, 2019
codecov.yml
common_test.go Consolidate mock_test.go and common_test.go Dec 16, 2017
config.go Update DeleteConfigKey to return old value Jun 17, 2019
config_test.go Satisify linter by randomizing some constant strings Jun 17, 2019
constants.go Update documentation example to quote JSON keys Apr 11, 2019
db.go
db_test.go Convert RevsDiff to a stream producer Jun 25, 2019
doc.go Remove documentation about contexts. This should be well known by now Jun 21, 2019
errors.go Add documentation about how to use the Error type Jun 6, 2019
errors_test.go Add Message field to error type Jun 6, 2019
find.go Update a bunch of errors to use Message: instead of Err: errors.New(...) Jun 6, 2019
find_test.go Mock Rows interface Dec 16, 2017
glide.gopherjs.yaml Refactor mergeOptions not to depend on mergo library Feb 6, 2019
glide.yaml Update deps Dec 15, 2017
iterator.go Pass JSON unmarshaling errors through unaltered Jun 9, 2019
iterator_test.go Pass JSON unmarshaling errors through unaltered Jun 9, 2019
kivik.go Update a bunch of errors to use Message: instead of Err: errors.New(...) Jun 6, 2019
kivik_test.go Make CreateDB() return just an error Mar 12, 2019
package.json Update paths Dec 14, 2017
registry.go Update paths Dec 14, 2017
registry_test.go Use mock package for Driver and DB types Dec 16, 2017
replication.go
replication_test.go Mock Client interface Dec 16, 2017
rows.go Update a bunch of errors to use Message: instead of Err: errors.New(...) Jun 6, 2019
rows_test.go
security.go Add GET /_security for CouchDB Mar 17, 2017
session.go Update a bunch of errors to use Message: instead of Err: errors.New(...) Jun 6, 2019
session_test.go Mock Sessioner interface Dec 16, 2017
updates.go Update a bunch of errors to use Message: instead of Err: errors.New(...) Jun 6, 2019
updates_test.go Allow passing ctx to DBUpdates() method, and update docs Feb 15, 2019
xerrors_13.go Add FormatError method to Error type Jun 5, 2019
xerrors_pre13.go

README.md

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 development branch of Kivik. The stable version is available here. Please consult the documentation on that page for proper installation of the stable branch.

This branch which will eventually become the Kivik 2.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 1.x release of Kivik, which is stable.

Example configuration for common dependency managers follow.

dep

Update your Gopkg.toml file:

[[constraint]]
  name = "github.com/go-kivik/kivik"
  branch = "master"

[[constraint]]
  name = "github.com/go-kivik/couchdb"
  branch = "master"

Glide

Update your glide.yaml file:

import:
- package: github.com/go-kivik/kivik
  version: master
- package: github.com/go-kivik/couchdb
  version: master

govendor

Fetch the latest development version of Kivik and the CouchDB driver with the following command:

    govendor fetch github.com/go-kivik/kivik
    govendor fetch github.com/go-kivik/couchdb

Installation

Install Kivik as you normally would for any Go package:

go get -u github.com/go-kivik/kivik
go get -u github.com/go-kivik/couchdb

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 (
    "context"
    "fmt"

    // "github.com/flimzy/kivik" // Stable version of Kivik
    "github.com/go-kivik/kivik" // Development version of Kivik
    _ "github.com/go-kivik/couchdb" // The CouchDB driver
)

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

    db, err := client.DB(context.TODO(), "animals")
    if err != nil {
        panic(err)
    }

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

    rev, err := db.Put(context.TODO(), "cow", doc)
    if err != nil {
        panic(err)
    }
    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 LICENSE.md 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 and OSX for every pull request, but should work on all supported Go platforms.

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 2.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 1.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 1.x PouchDB driver aims for compatibility with all stable releases of PouchDB from 6.0.0.

What is the development status?

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

Kivik 2.x is under development, and adds new features and a streamlined API.

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 LICENCE.md, 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.
You can’t perform that action at this time.