README.md
1[![Build Status](https://travis-ci.org/go-kivik/kivik.svg?branch=master)](https://travis-ci.org/go-kivik/kivik) [![Codecov](https://img.shields.io/codecov/c/github/go-kivik/kivik.svg?style=flat)](https://codecov.io/gh/go-kivik/kivik) [![Go Report Card](https://goreportcard.com/badge/github.com/go-kivik/kivik)](https://goreportcard.com/report/github.com/go-kivik/kivik) [![GoDoc](https://godoc.org/github.com/go-kivik/kivik?status.svg)](http://godoc.org/github.com/go-kivik/kivik) [![Website](https://img.shields.io/website-up-down-green-red/http/shields.io.svg?label=website&colorB=007fff)](http://kivik.io)
2
3# Kivik
4
5Package kivik provides a common interface to CouchDB or CouchDB-like databases.
6
7The kivik package must be used in conjunction with a database driver.
8
9The kivik driver system is modeled after the standard library's [sql](https://golang.org/pkg/database/sql/)
10and [sql/driver](https://golang.org/pkg/database/sql/driver/) packages, although
11the client API is completely different due to the different database models
12implemented by SQL and NoSQL databases such as CouchDB.
13
14# Versions
15
16You are browsing the _development_ branch of Kivik. The stable version is
17available [here](https://github.com/go-kivik/kivik/tree/stable1.x).
18
19This branch which will eventually become the Kivik 2.0.0 release. The API is
20subject to rapid and unannounced changes at this stage of development. For
21production work, you are encouraged to use the latest 1.x release of Kivik,
22which is stable.
23
24To use the stable version of Kivik, please use a dependency manager to ensure
25you're using version 1.x of Kivik and the Kivik driver.
26
27Example configs for common dependency managers follow.
28
29## [dep](https://github.com/golang/dep)
30
31Update your `Gopkg.toml` file:
32
33```toml
34[[constraint]]
35 name = "github.com/flimzy/kivik"
36 version = "^1.6.0"
37
38[[constraint]]
39 name = "github.com/go-kivik/couchdb"
40 version = "^1.6.0"
41```
42
43## [Glide](https://github.com/Masterminds/glide)
44
45Update your `glide.yaml` file:
46
47```yaml
48import:
49- package: github.com/flimzy/kivik
50 version: ^1.6.0
51- package: github.com/go-kivik/couchdb
52 version: ^1.6.0
53```
54
55## [govendor](https://github.com/kardianos/govendor)
56
57Fetch the latest stable version of Kivik and the CouchDB driver with the
58following command:
59
60 govendor fetch github.com/flimzy/kivik@v1
61 govendor fetch github.com/go-kivik/couchdb@v1
62
63# Installation
64
65Install Kivik as you normally would for any Go package:
66
67 go get -u github.com/go-kivik/kivik
68 go get -u github.com/go-kivik/couchdb
69
70This will install the main Kivik package and the CouchDB database driver. See
71the [list of Kivik database drivers](https://github.com/go-kivik/kivik/wiki/Kivik-database-drivers)
72for a complete list of available drivers.
73
74# Example Usage
75
76Please consult the the [package documentation](https://godoc.org/github.com/go-kivik/kivik)
77for all available API methods, and a complete usage documentation. And for
78additional usage examples, [consult the wiki](https://github.com/go-kivik/kivik/wiki/Usage-Examples).
79
80```go
81package main
82
83import (
84 "context"
85 "fmt"
86
87 // "github.com/flimzy/kivik" // Stable version of Kivik
88 "github.com/go-kivik/kivik" // Development version of Kivik
89 _ "github.com/go-kivik/couchdb" // The CouchDB driver
90)
91
92func main() {
93 client, err := kivik.New(context.TODO(), "couch", "http://localhost:5984/")
94 if err != nil {
95 panic(err)
96 }
97
98 db, err := client.DB(context.TODO(), "animals")
99 if err != nil {
100 panic(err)
101 }
102
103 doc := map[string]interface{}{
104 "_id": "cow",
105 "feet": 4,
106 "greeting": "moo",
107 }
108
109 rev, err := db.Put(context.TODO(), "cow", doc)
110 if err != nil {
111 panic(err)
112 }
113 fmt.Printf("Cow inserted with revision %s\n", rev)
114}
115```
116
117# Frequently Asked Questions
118
119Nobody has ever asked me any of these questions, so they're probably better called
120"Never Asked Questions" or possibly "Imagined Questions."
121
122## Why another CouchDB client API?
123
124Read the [design goals](https://github.com/go-kivik/kivik/wiki/Design-goals) for
125the general design goals.
126
127Specifically, I was motivated to write Kivik for a few reasons:
128
1291. I was unhappy with any of the existing CouchDB drivers for Go. The [best
130one](https://github.com/fjl/go-couchdb) had a number of shortcomings:
131
132 - It is no longer actively developed.
133 - It [doesn't have an open source license](https://github.com/fjl/go-couchdb/issues/15).
134 - It doesn't support iterating over result sets, forcing one to load all
135 results of a query into memory at once.
136 - It [doesn't support CouchDB 2.0](https://github.com/fjl/go-couchdb/issues/14)
137 sequence IDs or MongoDB-style queries.
138 - It doesn't natively support CookieAuth (it does allow a generic Auth method
139 which could be used to do this, but I think it's appropriate to put directly
140 in the library).
141
1422. I wanted a single client API that worked with both CouchDB and
143[PouchDB](https://pouchdb.com/). I had previously written
144[go-pouchdb](https://github.com/flimzy/go-pouchdb), a GopherJS wrapper around
145the PouchDB library with a public API modeled after `fjl/go-couchdb`, but I
146still wanted a unified driver infrastructure.
147
1483. I want an unambiguous, open source license. This software is released under
149the Apache 2.0 license. See the included LICENSE.md file for details.
150
1514. I wanted the ability to mock CouchDB connections for testing. This is possible
152with the `sql` / `sql/driver` approach by implementing a mock driver, but was
153not possible with any existing CouchDB client libraries. This library makes that
154possible for CouchDB apps, too.
155
1565. I wanted a simple, mock CouchDB server I could use for testing. It doesn't
157need to be efficient, or support all CouchDB servers, but it should be enough
158to test the basic functionality of a PouchDB app, for instance. Kivik aims to
159do this with the `kivik serve` command, in the near future.
160
1616. I wanted a toolkit that would make it easy to build a proxy to sit in front
162of CouchDB to handle custom authentication or other logic that CouchDB cannot
163support natively. Kivik aims to accomplish this in the future.
164
165## What are Kivik's requirements?
166
167Kivik's test suite is automatically run on Linux and OSX for every pull request,
168but should work on all supported Go platforms.
169
170Below are the compatibility targets for specific runtime and database versions.
171If you discover a bug affecting any of these supported environments, please let
172me know by submitting a bug report via GitHub.
173
174- **Go** Kivik 2.x aims for full compatibility with all stable releases of Go
175 from 1.8. For Go 1.7, you can use [Kivik 1.x](https://github.com/go-kivik/kivik/tree/stable1.x)
176- **CouchDB** The Kivik 1.x CouchDB driver aims for compatibility with all
177 stable releases of CouchDB from 1.6.1.
178- **GopherJS** GopherJS always requires the latest stable version of Go, so
179 building Kivik with GopherJS has this same requirement.
180- **PouchDB** The Kivik 1.x PouchDB driver aims for compatibility with all
181 stable releases of PouchDB from 6.0.0.
182
183## What is the development status?
184
185Kivik comes with a complete client API client and backend drivers for CouchDB
186and PouchDB.
187
188My next priorities are to work on fleshing out the Memory driver, which will
189make automated testing without a real CouchDB server easier. Then I will work
190on completing the 'serve' mode.
191
192You can see a complete overview of the current status on the
193[Compatibility chart](https://github.com/go-kivik/kivik/blob/master/doc/COMPATIBILITY.md)
194
195## Why the name "Kivik"?
196
197[Kivik](http://www.ikea.com/us/en/catalog/categories/series/18329/) is a line
198of sofas (couches) from IKEA. And in the spirit of IKEA, and build-your-own
199furniture, Kivik aims to allow you to "build your own" CouchDB client, server,
200and proxy applications.
201
202## What license is Kivik released under?
203
204This software is released under the terms of the Apache 2.0 license. See
205LICENCE.md, or read the [full license](http://www.apache.org/licenses/LICENSE-2.0).
206