github.com/go-kivik/kivik/v4@v4.3.2/README.md (about)

     1  [![Build Status](https://gitlab.com/go-kivik/kivik/badges/master/pipeline.svg)](https://gitlab.com/go-kivik/kivik/pipelines) [![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) [![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4) [![Website](https://img.shields.io/website-up-down-green-red/http/kivik.io.svg?label=website&colorB=007fff)](http://kivik.io)
     2  
     3  # Kivik
     4  
     5  Package kivik provides a common interface to CouchDB or CouchDB-like databases.
     6  
     7  The kivik package must be used in conjunction with a database driver.
     8  
     9  The kivik driver system is modeled after the standard library's [sql](https://golang.org/pkg/database/sql/)
    10  and [sql/driver](https://golang.org/pkg/database/sql/driver/) packages, although
    11  the client API is completely different due to the different database models
    12  implemented by SQL and NoSQL databases such as CouchDB.
    13  
    14  # Versions
    15  
    16  You are browsing the current **stable** branch of Kivik, v4. If you are upgrading
    17  from the previous stable version, v3, [read the list of breaking changes](#changes-from-3x-to-4x).
    18  
    19  Example configuration for common dependency managers follow.
    20  
    21  ## Go Modules
    22  
    23  Kivik 3.x and later supports Go modules, which is the recommended way to use it
    24  for Go version 1.11 or newer. Kivik 4.x only supports Go 1.17 and later. If your
    25  project is already using Go modules, simply fetch the desired version:
    26  
    27  ```shell
    28  go get github.com/go-kivik/kivik/v4
    29  ```
    30  
    31  # Installation
    32  
    33  Install Kivik as you normally would for any Go package:
    34  
    35      go get -u github.com/go-kivik/kivik/v4
    36  
    37  This will install the main Kivik package and the CouchDB database driver. Three officially supported drivers are shipped with this Go module:
    38  
    39    - CouchDB: [github.com/go-kivik/kivik/v4/couchdb](https://pkg.go.dev/github.com/go-kivik/kivik/v4/couchdb)
    40    - PouchDB: [github.com/go-kivik/kivik/v4/pouchdb](https://pkg.go.dev/github.com/go-kivik/kivik/v4/pouchdb) (requires GopherJS)
    41    - MockDB: [github.com/go-kivik/kivik/v4/mockdb](https://pkg.go.dev/github.com/go-kivik/kivik/v4/mockdb)
    42  
    43  In addition, there are partial/experimental drivers available:
    44  
    45    - FilesystemDB: [github.com/go-kivik/kivik/v4/x/fsdb](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/fsdb)
    46    - MemoryDB: [github.com/go-kivik/kivik/v4/x/memorydb](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/memorydb)
    47    - SQLite: [github.com/go-kivik/kivik/x/sqlite/v4](https://pkg.go.dev/github.com/go-kivik/kivik/x/sqlite/v4)
    48  
    49  # CLI
    50  
    51  Consult the [CLI README](https://github.com/go-kivik/kivik/blob/master/cmd/kivik/README.md) for full details on the `kivik` CLI tool.
    52  
    53  # Example Usage
    54  
    55  Please consult the the [package documentation](https://pkg.go.dev/github.com/go-kivik/kivik/v4)
    56  for all available API methods, and a complete usage documentation, and usage examples.
    57  
    58  ```go
    59  package main
    60  
    61  import (
    62      "context"
    63      "fmt"
    64  
    65      kivik "github.com/go-kivik/kivik/v4"
    66      _ "github.com/go-kivik/kivik/v4/couchdb" // The CouchDB driver
    67  )
    68  
    69  func main() {
    70      client, err := kivik.New("couch", "http://localhost:5984/")
    71      if err != nil {
    72          panic(err)
    73      }
    74  
    75      db := client.DB("animals")
    76  
    77      doc := map[string]interface{}{
    78          "_id":      "cow",
    79          "feet":     4,
    80          "greeting": "moo",
    81      }
    82  
    83      rev, err := db.Put(context.TODO(), "cow", doc)
    84      if err != nil {
    85          panic(err)
    86      }
    87      fmt.Printf("Cow inserted with revision %s\n", rev)
    88  }
    89  ```
    90  
    91  # Frequently Asked Questions
    92  
    93  Nobody has ever asked me any of these questions, so they're probably better called
    94  "Never Asked Questions" or possibly "Imagined Questions."
    95  
    96  ## Why another CouchDB client API?
    97  
    98  I had a number of specific design goals when creating this package:
    99  
   100  - 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.
   101  - Work equally well with CouchDB 1.6, 2.x, 3.x, and any future versions, as well as PouchDB.
   102  - Be as Go-idiomatic as possible.
   103  - Be unambiguously open-source. Kivik is released under the Apache license, same as CouchDB and PouchDB.
   104  - 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.
   105  
   106  ## What are Kivik's requirements?
   107  
   108  Kivik's test suite is automatically run on Linux for every pull request, but
   109  should work on all supported Go architectures. If you find it not working for
   110  your OS/architecture, please submit a bug report.
   111  
   112  Below are the compatibility targets for specific runtime and database versions.
   113  If you discover a bug affecting any of these supported environments, please let
   114  me know by submitting a bug report via GitHub.
   115  
   116  - **Go** Kivik 4.x aims for full compatibility with all stable releases of Go
   117    from 1.13. For Go 1.7 or 1.8 you can use [Kivik 1.x](https://github.com/go-kivik/kivik/tree/v1).
   118    For Go 1.9 through 1.12, you can use [Kivik 3.x](https://github.com/go-kivik/kivik/tree/v3).
   119  - **CouchDB** The Kivik 4.x CouchDB driver aims for compatibility with all
   120    stable releases of CouchDB from 2.x.
   121  - **GopherJS** GopherJS always requires the latest stable version of Go, so
   122    building Kivik with GopherJS has this same requirement.
   123  - **PouchDB** The Kivik 4.x PouchDB driver aims for compatibility with all
   124    stable releases of PouchDB from 8.0.0.
   125  
   126  ## What is the development status?
   127  
   128  Kivik 4.x is stable, and suitable for production use.
   129  
   130  ## Why the name "Kivik"?
   131  
   132  [Kivik](http://www.ikea.com/us/en/catalog/categories/series/18329/) is a line
   133  of sofas (couches) from IKEA. And in the spirit of IKEA, and build-your-own
   134  furniture, Kivik aims to allow you to "build your own" CouchDB client, server,
   135  and proxy applications.
   136  
   137  ## What license is Kivik released under?
   138  
   139  Kivik is Copyright 2017-2023 by the Kivik contributors, and is released under the
   140  terms of the Apache 2.0 license. See [LICENCE](LICENSE) for the full text of the
   141  license.
   142  
   143  ### Changes from 3.x to 4.x
   144  
   145  This is a partial list of breaking changes between 3.x and 4.x
   146  
   147  - 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.
   148  - The `Authenticate` method has been removed. Authentication is now handled via option parameters.
   149  - The CouchDB, PouchDB, and MockDB drivers, and the experimental FilesystemDB and MemoryDB drivers, have been merged with this repo, rather than being hosted in separate repos. For v3 you would have imported `github.com/go-kivik/couchdb/v3`, for example. With v4, you instead use `github.com/go-kivik/kivik/v4/couchdb` for CouchDB, or `github.com/go-kivik/kivik/v4/x/fsdb` for the experimental FilesystemDB driver.
   150  - The return type for queries has been significantly changed.
   151    - In 3.x, queries returned a `*Rows` struct. Now they return a `*ResultSet`.
   152    - 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](https://github.com/go-kivik/kivik/issues/552).
   153    - Calling most methods on `ResultSet` will now work after closing the iterator.
   154    - The new `ResultSet` type supports multi-query mode, which is triggered by calling `NextResultSet` before `Next`.
   155    - `Key`, `ID`, `Rev`, `Attachments` all now return row-specific errors, and `ScanKey` may successfully decode while also returning a row-specific error.
   156  - 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.
   157  - The `DBUpdates()` and `Changes()` methods now defer errors to the iterator, for easier chaining and consistency with other iterators.
   158  - `DB.BulkDocs()` no longer returns an iterator, but rather an array of all results.
   159  - `Get` now returns a simpler `*Result` type than before.
   160  - `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.
   161  - 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.
   162  - `Client.Close()` and `DB.Close()` now block until any relevant calls have returned.
   163  - `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.
   164  
   165  #### CouchDB specific changes
   166  
   167  - The `SetTransport` authentication method has been removed, as a duplicate of [couchdb.OptionHTTPClient](https://pkg.go.dev/github.com/go-kivik/kivik/v4/couchdb#OptionHTTPClient).
   168  - 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.
   169  
   170  #### New features and additions
   171  
   172  - Kivik now ships with the `kivik` command line tool (previously part of the `github.com/go-kivik/xkivik` repository).
   173  - The new [Replicate](https://pkg.go.dev/github.com/go-kivik/kivik/v4#Replicate) function allows replication between arbitrary databases, such as between CouchDB and a directory structure using the FilesystemDB.
   174  
   175  ## What projects currently use Kivik?
   176  
   177  If your project uses Kivik, and you'd like to be added to this list, create an
   178  issue or submit a pull request.
   179  
   180  - [Cayley](https://github.com/cayleygraph/cayley) is an open-source graph
   181    database. It uses Kivik for the CouchDB and PouchDB storage backends.