couchdb

Documentation

Overview

Package couchdb provides the powerful as well as convenient Tideland Go CouchDB Client as client for the CouchDB database.

A connection to the database or at least a server can be established by calling

cdb, err := couchdb.Open(cfg)

The expected configuration is

{etc
    {hostname <hostname||localhost>}
    {port <port||5984>}
    {database <database||default>}
    {debug-logging <true/false||false>}
}

If any of the values isn't defined the default values above are taken. Instead of splitting a larger configuration it's also possible to use

cdb, err := couchdb.OpenPath(cfg, "path/to/couchdb/config")

In case of not using the etc configuration package there's the little helper to create a configuration by calling

cfg := couchdb.Configure(hostname, port, database)

The supported operations are the listing, creation, and deleting of databases, the listing of all design documents and data documents, and the creation, reading, updating, and deleting of documents.

Index

• Constants
• func Configure(hostname string, port int, database string) (etc.Etc, error)
• type CouchDB
  • func Open(cfg etc.Etc, params ...Parameter) (CouchDB, error)
  • func OpenPath(cfg etc.Etc, path string, params ...Parameter) (CouchDB, error)
• type Design
• type KeyValue
• type Parameter
  • func Header(kvs ...KeyValue) Parameter
  • func Query(kvs ...KeyValue) Parameter
  • func Revision(revision string) Parameter
• type Parameterizable
• type ResultSet
• type Status
• type Statuses
• type Unmarshable
  • func NewUnmarshableJSON(msg json.RawMessage) Unmarshable
  • func NewUnmarshableRaw(raw []byte) Unmarshable

Constants

const (
	ErrNoConfiguration = iota + 1
	ErrInvalidVersion
	ErrInvalidDocument
	ErrNoIdentifier
	ErrNotFound
	ErrMarshallingDoc
	ErrPreparingRequest
	ErrPerformingRequest
	ErrClientRequest
	ErrUnmarshallingDoc
	ErrUnmarshallingField
	ErrReadingResponseBody
)

Error codes.

const (
	StatusOK       = http.StatusOK
	StatusCreated  = http.StatusCreated
	StatusAccepted = http.StatusAccepted

	StatusFound = http.StatusFound

	StatusBadRequest         = http.StatusBadRequest
	StatusUnauthorized       = http.StatusUnauthorized
	StatusForbidden          = http.StatusForbidden
	StatusNotFound           = http.StatusNotFound
	StatusMethodNotAllowed   = http.StatusMethodNotAllowed
	StatusNotAcceptable      = http.StatusNotAcceptable
	StatusConflict           = http.StatusConflict
	StatusPreconditionFailed = http.StatusPreconditionFailed
	StatusTooManyRequests    = http.StatusTooManyRequests

	StatusInternalServerError = http.StatusInternalServerError
)

Status codes after database requests.

Functions

func Configure

func Configure(hostname string, port int, database string) (etc.Etc, error)

Configure creates a configuration out of the passed arguments.

Types

type CouchDB

type CouchDB interface {
	// Path creates a document path starting at root.
	Path(parts ...string) string

	// DatabasePath creates a document path for the database.
	DatabasePath(parts ...string) string

	// Head performs a GET request against the configured database.
	Head(path string, doc interface{}, params ...Parameter) ResultSet

	// Get performs a GET request against the configured database.
	Get(path string, doc interface{}, params ...Parameter) ResultSet

	// Put performs a GET request against the configured database.
	Put(path string, doc interface{}, params ...Parameter) ResultSet

	// Post performs a GET request against the configured database.
	Post(path string, doc interface{}, params ...Parameter) ResultSet

	// Delete performs a GET request against the configured database.
	Delete(path string, doc interface{}, params ...Parameter) ResultSet

	// GetOrPost decides based on the document if it will perform
	// a GET request or a POST request. The document can be set directly
	// or by one of the parameters. Several of the CouchDB commands
	// work this way.
	GetOrPost(path string, doc interface{}, params ...Parameter) ResultSet

	// Version returns the version number of the database instance.
	Version() (version.Version, error)

	// AllDatabases returns a list of all database IDs
	// of the connected server.
	AllDatabases() ([]string, error)

	// HasDatabase checks if the configured database exists.
	HasDatabase() (bool, error)

	// CreateDatabase creates the configured database.
	CreateDatabase(params ...Parameter) ResultSet

	// DeleteDatabase removes the configured database.
	DeleteDatabase(params ...Parameter) ResultSet

	// AllDesigns returns the list of all design
	// document IDs of the configured database.
	AllDesigns() ([]string, error)

	// Design returns the design document instance for
	// the given ID.
	Design(id string) (Design, error)

	// AllDocuments returns a list of all document IDs
	// of the configured database.
	AllDocuments() ([]string, error)

	// HasDocument checks if the document with the ID exists.
	HasDocument(id string) (bool, error)

	// CreateDocument creates a new document.
	CreateDocument(doc interface{}, params ...Parameter) ResultSet

	// ReadDocument reads an existing document.
	ReadDocument(id string, params ...Parameter) ResultSet

	// UpdateDocument update an existing document.
	UpdateDocument(doc interface{}, params ...Parameter) ResultSet

	// DeleteDocument deletes an existing document.
	DeleteDocument(doc interface{}, params ...Parameter) ResultSet

	// DeleteDocumentByID deletes an existing document simply by
	// its identifier and revision.
	DeleteDocumentByID(id, revision string, params ...Parameter) ResultSet

	// BulkWriteDocuments allows to create or update many
	// documents en bloc.
	BulkWriteDocuments(docs []interface{}, params ...Parameter) (Statuses, error)
}

CouchDB provides the access to a database.

func Open

func Open(cfg etc.Etc, params ...Parameter) (CouchDB, error)

Open returns a configured connection to a CouchDB server. Permanent parameters, e.g. for authentication, are possible.

func OpenPath

func OpenPath(cfg etc.Etc, path string, params ...Parameter) (CouchDB, error)

OpenPath returns a configured connection to a CouchDB server. The configuration is part of a larger configuration and the path leads to its location. Permanent parameters, e.g. for authentication, are possible.

type Design

type Design interface {
	// ID returns the ID of the design.
	ID() string

	// Language returns the language for views and shows.
	Language() string

	// Language sets the language for views and shows.
	SetLanguage(language string)

	// View returns the map and the reduce functions of the
	// view with the ID, otherwise false.
	View(id string) (string, string, bool)

	// SetView sets the map and the reduce functions of the
	// view with the ID.
	SetView(id, mapf, reducef string)

	// Show returns the show function with the ID, otherwise false.
	Show(id string) (string, bool)

	// SetShow sets the show function with the ID.
	SetShow(id, showf string)

	// Write creates a new design document or updates an
	// existing one.
	Write(rps ...Parameter) ResultSet

	// Delete a design document.
	Delete(rps ...Parameter) ResultSet
}

Design provides convenient access to a design document.

type KeyValue

type KeyValue struct {
	Key   string
	Value string
}

KeyValue is used for generic query and header parameters.

type Parameter

type Parameter func(pa Parameterizable)

Parameter is a function changing one (or if needed multile) parameter.

func Header

func Header(kvs ...KeyValue) Parameter

Header is generic for setting request header parameters.

func Query

func Query(kvs ...KeyValue) Parameter

Query is generic for setting request query parameters.

func Revision

func Revision(revision string) Parameter

Revision sets the revision for the access to concrete document revisions.

type Parameterizable

type Parameterizable interface {
	// SetQuery sets a query parameter.
	SetQuery(key, value string)

	// AddQuery adds a query parameter to an existing one.
	AddQuery(key, value string)

	// SetHeader sets a header parameter.
	SetHeader(key, value string)

	// UpdateDocument allows to modify or exchange the document.
	UpdateDocument(update func(interface{}) interface{})
}

Parameterizable defines the methods needed to apply the parameters.

type ResultSet

type ResultSet interface {
	// IsOK checks the status code if the result is okay.
	IsOK() bool

	// StatusCode returns the status code of the request.
	StatusCode() int

	// Error returns a possible error of a request.
	Error() error

	// ID returns a potentially returned document identifier.
	ID() string

	// Revision returns a potentially returned document revision.
	Revision() string

	// IsDeleted returns true if a returned document is already deleted.
	IsDeleted() bool

	// Document returns the received document of a client
	// request and unmorshals it.
	Document(value interface{}) error

	// Raw returns the received raw data of a client request.
	Raw() ([]byte, error)

	// Header provides access to header variables.
	Header(key string) string
}

ResultSet contains the server result set.

type Status

type Status struct {
	OK       bool   `json:"ok"`
	ID       string `json:"id"`
	Revision string `json:"rev"`
	Error    string `json:"error"`
	Reason   string `json:"reason"`
}

Status contains internal status information CouchDB returns.

type Statuses

type Statuses []Status

Statuses is the list of status information after a bulk writing.

type Unmarshable

type Unmarshable interface {
	// String returns the original as string.
	String() string

	// Raw returns the unmarshable as raw byte slice.
	Raw() []byte

	// Unmarshal unmarshals the interface into the
	// passed variable.
	Unmarshal(doc interface{}) error
}

Unmarshable describes a not yet unmarshalled value that can be unmarshalled into a given variable. It is used to access key, value, or document of view result rows.

func NewUnmarshableJSON

func NewUnmarshableJSON(msg json.RawMessage) Unmarshable

NewUnmarshableJSON creates a new Unmarshable out of a json.RawMessage

func NewUnmarshableRaw

func NewUnmarshableRaw(raw []byte) Unmarshable

NewUnmarshableRaw creates a new Unmarshable out of the raw bytes.