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 branch.
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.
Example configuration for common dependency managers follow.
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 github.com/go-kivik/kivik/v3 # Stable release
go get github.com/go-kivik/kivik/v4 # Development release
Installation
Install Kivik as you normally would for any Go package:
go get -u github.com/go-kivik/kivik/v4
go get -u github.com/go-kivik/couchdb/v4
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"
kivik "github.com/go-kivik/kivik/v4"
_ "github.com/go-kivik/couchdb/v4" // The CouchDB driver
)
func main() {
client, err := kivik.New("couch", "http://localhost:5984/")
if err != nil {
panic(err)
}
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 {
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."
Read the design goals for the general design goals.
Specifically, I was motivated to write Kivik for a few reasons:
I was unhappy with any of the existing CouchDB drivers for Go. The best one had a number of shortcomings:
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.
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.
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.
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.
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.
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.
Kivik 4.x is under active development, and subject to radical, and unannounced API changes. For production use, please use Kivik 3.x.
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.
Kivik is Copyright 2017-2023 by the Kivik contributors, and is released under the terms of the Apache 2.0 license. See LICENCE for the full text of the license.
This is a partial list of breaking changes between 3.x and 4.x
*Rows
struct. Now they return the ResultSet
interface.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.ResultSet
will now work after closing the iterator.ResultSet
type supports multi-query mode, which is triggered by calling NextResultSet
before Next
.ScanDoc
, ScanKey
, ScanValue
, Key
, or ID
before calling Next
or NextResultSet
will make the iterator operate in single-item mode, meaning that only the first item in the iterator will be processed, then the iterator will be closed immediately.Key
, ID
, Rev
, Attachments
all now return row-specific errors, and ScanKey
may successfully decode while also returning a row-specific error.Changes
type has been changed to semantically match the ResultSet
type. Specifically, the LastSeq()
and Pending()
methods have been replaced by the Metadata()
method.DBUpdates()
and Changes()
methods now defer errors to the iterator, for easier chaining and consistency with other iterators.BulkDocs()
no longer returns an iterator, but rather an array of all results.Get
now returns a ResultSet
, rather than a *Row
. Semantics work roughly the same for standard use cases where Get
returns a single document: Just call ScanDoc
as before. However, this allows Get
to also return multiple docs, as it does when called with the open_revs
flag. See the CouchDB docs.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.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.If your project uses Kivik, and you'd like to be added to this list, create an issue or submit a pull request.
Author: Go-kivik
Source Code: https://github.com/go-kivik/kivik
License: Unknown, Apache-2.0 licenses found