couchdb

README

Kivik CouchDB

CouchDB driver for Kivik.

Usage

This package provides an implementation of the github.com/go-kivik/kivik/v4/driver interface. You must import the driver and can then use the full Kivik API.

package main

import (
    "context"

    kivik "github.com/go-kivik/kivik/v4"
    _ "github.com/go-kivik/kivik/v4/couchdb" // The CouchDB driver
)

func main() {
    client, err := kivik.New(context.TODO(), "couch", "")
    // ...
}

License

This software is released under the terms of the Apache 2.0 license. See LICENCE.md, or read the full license.

Documentation

Overview

Package couchdb is a driver for connecting with a CouchDB server over HTTP.

General Usage

Use the `couch` driver name when using this driver. The DSN should be a full URL, likely with login credentials:

import (
	kivik "github.com/go-kivik/kivik/v4"
	_ "github.com/go-kivik/kivik/v4/couchdb" // The CouchDB driver
)

client, err := kivik.New("couch", "http://username:password@127.0.0.1:5984/")

Options

The CouchDB driver generally interprets github.com/go-kivik/kivik/v4.Params keys and values as URL query parameters. Values of the following types will be converted to their ppropriate string representation when URL-encoded:

• bool
• string
• []string
• int, uint, uint8, uint16, uint32, uint64, int8, int16, int32, int64

Passing any other type will return an error.

CouchDB also accepts a few special-case options defined in this package.

Authentication

The CouchDB driver supports a number of authentication methods. For most uses, you don't need to worry about authentication at all--just include authentication credentials in your connection DSN:

client, _ := kivik.New("couch", "http://user:password@localhost:5984/")

This will use Cookie authentication by default (or BasicAuth if compiled with GopherJS).

To use one of the explicit authentication mechanisms, pass one of the authentication options to [New]. For example:

client, _ := kivik.New("couch", "http://localhost:5984/", couchdb.BasicAuth("bob", "secret"))

Connection Options

Calls to github.com/go-kivik/kivik/v4.New may include options. OptionUserAgent and OptionHTTPClient are the only options honored. Example:

client, _ := kivik.New("couch", "http://localhost:5984/",
	couchdb.OptionUserAgent("My Custom User Agent String"),
	couchdb.OptionHTTPClient(&http.Client{
		Timeout: 15, // A shorter request timeout
	}),
)

Multipart PUT

Normally, to include an attachment in a CouchDB document, it must be base-64 encoded, which leads to increased network traffic and higher CPU load. CouchDB also supports the option to upload multiple attachments in a single request using the 'multipart/related' content type.

This is supported by the Kivik CouchDB driver as well. To take advantage of this capability, the `doc` argument to github.com/go-kivik/kivik/v4.DB.Put must be either:

• a map of type `map[string]interface{}`, with a key called `_attachments', and value of type github.com/go-kivik/kivik/v4.Attachments or pointer to github.com/go-kivik/kivik/v4.Attachments
• a struct, with a field having the tag `json:"_attachment"`, and the field having the type github.com/go-kivik/kivik/v4.Attachments or pointer to github.com/go-kivik/kivik/v4.Attachments.

With this in place, the CouchDB driver will switch to `multipart/related` mode, sending each attachment in binary format, rather than base-64 encoding it.

To function properly, each attachment must have an accurate github.com/go-kivik/kivik/v4.Attachment.Size value. If github.com/go-kivik/kivik/v4.Attachment.Size is unset, the entirely attachment may be read to determine its size, prior to sending it over the network, leading to delays and unnecessary I/O and CPU usage. The simplest way to ensure efficiency is to use NewAttachment. See the documentation on that function for proper usage.

Example:

file, _ := os.Open("/path/to/photo.jpg")
atts := &kivik.Attachments{
    "photo.jpg": NewAttachment("photo.jpg", "image/jpeg", file),
}
doc := map[string]interface{}{
    "_id":          "user123",
    "_attachments": atts,
}
rev, err := db.Put(ctx, "user123", doc)

To disable the `multipart/related` capabilities entirely, you may pass the OptionNoMultipartPut option. This will fallback to the default of inline base-64 encoding the attachments. Example:

rev, err := db.Put(ctx, "user123", doc", couchdb.OptionNoMultipartPut())

Server config for CouchDB 1.x

CouchDB allows querying the server configuration via the /_config endpoint. This is supported with the github.com/go-kivik/kivik/v4.DB.Config, github.com/go-kivik/kivik/v4.DB.ConfigSection, github.com/go-kivik/kivik/v4.DB.ConfigValue, github.com/go-kivik/kivik/v4.DB.SetConfigValue, and github.com/go-kivik/kivik/v4.DB.DeleteConfigKey methods. Each of these methods accepts a node argument, but CouchDB 1.x does not support per-node configuration via this endpoint. If you are still using CouchDB 1.x, leave the node argument empty, and this driver will revert to CouchDB-compatible operation.

Index

• func BasicAuth(username, password string) kivik.Option
• func CookieAuth(username, password string) kivik.Option
• func JWTAuth(token string) kivik.Option
• func NewAttachment(filename, contentType string, content io.Reader, size ...int64) (*kivik.Attachment, error)
• func OptionFullCommit() kivik.Option
• func OptionHTTPClient(client *http.Client) kivik.Option
• func OptionIfNoneMatch(value string) kivik.Option
• func OptionNoMultipartGet() kivik.Option
• func OptionNoMultipartPut() kivik.Option
• func OptionNoRequestCompression() kivik.Option
• func OptionPartition(partition string) kivik.Option
• func OptionUserAgent(ua string) kivik.Option
• func ProxyAuth(user, secret string, roles []string, headers ...map[string]string) kivik.Option

Functions

func BasicAuth

func BasicAuth(username, password string) kivik.Option

BasicAuth provides support for HTTP Basic authentication. Pass this option to github.com/go-kivik/kivik/v4.New to use Basic Authentication.

func CookieAuth

func CookieAuth(username, password string) kivik.Option

CookieAuth provides CouchDB Cookie auth. Cookie Auth is the default authentication method if credentials are included in the connection URL passed to github.com/go-kivik/kivik/v4.New. You may also pass this option as an argument to the same function, if you need to provide your auth credentials outside of the URL.

func JWTAuth

func JWTAuth(token string) kivik.Option

JWTAuth provides support for CouchDB JWT-based authentication. Kivik does no validation on the JWT token; it is passed verbatim to the server.

See https://docs.couchdb.org/en/latest/api/server/authn.html#jwt-authentication

func NewAttachment

func NewAttachment(filename, contentType string, content io.Reader, size ...int64) (*kivik.Attachment, error)

NewAttachment is a convenience function, which sets the size of the attachment based on content. This is intended for creating attachments to be uploaded using multipart/related capabilities of github.com/go-kivik/kivik/v4.DB.Put. The attachment size will be set to the first of the following found:

1. `size`, if present. Only the first value is considered.
2. content.Len(), if implemented (i.e. bytes.Buffer)
3. content.Stat().Size(), if implemented (i.e. os.File)
4. Read the entire content into memory, to determine the size. This can use a lot of memory for large attachments. Please use a file, or specify the size directly instead.

func OptionFullCommit

func OptionFullCommit() kivik.Option

OptionFullCommit is the option key used to set the `X-Couch-Full-Commit` header in the request when set to true.

func OptionHTTPClient

func OptionHTTPClient(client *http.Client) kivik.Option

OptionHTTPClient may be passed as an option when creating a CouchDB client to specify an custom net/http.Client to be used when making all API calls. Only honored by github.com/go-kivik/kivik/v4.New.

func OptionIfNoneMatch

func OptionIfNoneMatch(value string) kivik.Option

OptionIfNoneMatch is an option key to set the `If-None-Match` header on the request.

func OptionNoMultipartGet

func OptionNoMultipartGet() kivik.Option

OptionNoMultipartGet instructs github.com/go-kivik/kivik/v4.DB.Get not to use CouchDB's ability to download attachments with the multipart/related media type. This is only honored by calls to github.com/go-kivik/kivik/v4.DB.Get that request attachments.

func OptionNoMultipartPut

func OptionNoMultipartPut() kivik.Option

OptionNoMultipartPut instructs github.com/go-kivik/kivik/v4.DB.Put not to use CouchDB's multipart/related upload capabilities. This is only honored by calls to github.com/go-kivik/kivik/v4.DB.Put that also include attachments.

func OptionNoRequestCompression

func OptionNoRequestCompression() kivik.Option

OptionNoRequestCompression instructs the CouchDB client not to use gzip compression for request bodies sent to the server. Only honored by github.com/go-kivik/kivik/v4.New.

func OptionPartition

func OptionPartition(partition string) kivik.Option

OptionPartition instructs supporting methods to limit the query to the specified partition. Supported methods are: Query, AllDocs, Find, and Explain. Only supported by CouchDB 3.0.0 and newer.

See the CouchDB documentation.

func OptionUserAgent

func OptionUserAgent(ua string) kivik.Option

OptionUserAgent may be passed as an option when creating a client object, to append to the default User-Agent header sent on all requests.

func ProxyAuth

func ProxyAuth(user, secret string, roles []string, headers ...map[string]string) kivik.Option

ProxyAuth provides support for CouchDB's proxy authentication. Pass this option to github.com/go-kivik/kivik/v4.New to use proxy authentication.

The `secret` argument represents the couch_httpd_auth/secret value configured on the CouchDB server.

If `secret` is the empty string, the X-Auth-CouchDB-Token header will not be set, to support disabling the proxy_use_secret server setting.

The optional `headers` map may be passed to use non-standard header names. For instance, to use `X-User` in place of the `X-Auth-CouchDB-Username` header, pass a value of {"X-Auth-CouchDB-UserName": "X-User"}. The relevant headers are X-Auth-CouchDB-UserName, X-Auth-CouchDB-Roles, and X-Auth-CouchDB-Token.