couchdb

package module
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 25, 2017 License: BSD-3-Clause Imports: 20 Imported by: 27

README

CouchDB-Golang Library v1.2

A Golang library for working with CouchDB 2.x

supported Golang version:

  • 1.7.x

Build Status

  • Resource : a simple wrapper for HTTP requests and error handling
  • Server : CouchDB server instance
  • Database : CouchDB database instance
  • ViewResults : a representation of the results produced by design document views
  • ViewDefinition : a definition of view stored in a specific design document
  • Document : a representation of document object in database

Inspired by CouchDB-Python

Documentation

package couchdb
import "github.com/leesper/couchdb"

Constants

const (
    // DefaultBaseURL is the default address of CouchDB server.
    DefaultBaseURL = "http://localhost:5984"
)

Variables

var (
    // ErrBatchValue for invalid batch parameter of IterView
    ErrBatchValue = errors.New("batch must be 1 or more")
    // ErrLimitValue for invalid limit parameter of IterView
    ErrLimitValue = errors.New("limit must be 1 or more")
)

var (
    // ErrSetID for setting ID to document which already has one.
    ErrSetID = errors.New("id can only be set on new documents")
    // ErrNotStruct for not a struct value
    ErrNotStruct = errors.New("value not of struct type")
    // ErrNotDocumentEmbedded for not a document-embedded value
    ErrNotDocumentEmbedded = errors.New("value not Document-embedded")
)

var (

    // ErrNotModified for HTTP status code 304
    ErrNotModified = errors.New("status 304 - not modified")
    // ErrBadRequest for HTTP status code 400
    ErrBadRequest = errors.New("status 400 - bad request")
    // ErrUnauthorized for HTTP status code 401
    ErrUnauthorized = errors.New("status 401 - unauthorized")
    // ErrForbidden for HTTP status code 403
    ErrForbidden = errors.New("status 403 - forbidden")
    // ErrNotFound for HTTP status code 404
    ErrNotFound = errors.New("status 404 - not found")
    // ErrResourceNotAllowed for HTTP status code 405
    ErrResourceNotAllowed = errors.New("status 405 - resource not allowed")
    // ErrNotAcceptable for HTTP status code 406
    ErrNotAcceptable = errors.New("status 406 - not acceptable")
    // ErrConflict for HTTP status code 409
    ErrConflict = errors.New("status 409 - conflict")
    // ErrPreconditionFailed for HTTP status code 412
    ErrPreconditionFailed = errors.New("status 412 - precondition failed")
    // ErrBadContentType for HTTP status code 415
    ErrBadContentType = errors.New("status 415 - bad content type")
    // ErrRequestRangeNotSatisfiable for HTTP status code 416
    ErrRequestRangeNotSatisfiable = errors.New("status 416 - requested range not satisfiable")
    // ErrExpectationFailed for HTTP status code 417
    ErrExpectationFailed = errors.New("status 417 - expectation failed")
    // ErrInternalServerError for HTTP status code 500
    ErrInternalServerError = errors.New("status 500 - internal server error")
)

func FromJSONCompatibleMap

func FromJSONCompatibleMap(obj interface{}, docMap map[string]interface{}) error

FromJSONCompatibleMap constructs a Document-embedded struct from a JSON-compatible map.

func GenerateUUID

func GenerateUUID() string

GenerateUUID returns a random 128-bit UUID

func Load

func Load(db *Database, docID string, obj interface{}) error

Load loads the document in specified database.

func Store

func Store(db *Database, obj interface{}) error

Store stores the document in specified database.

func SyncMany

func SyncMany(db *Database, viewDefns []*ViewDefinition, removeMissing bool, callback func(map[string]interface{})) ([]UpdateResult, error)

SyncMany ensures that the views stored in the database match the views defined by the corresponding view definitions. This function might update more than one design document. This is done using CouchDB's bulk update to ensure atomicity of the opeation. db: the corresponding database.

viewDefns: a sequence of *ViewDefinition instances.

removeMissing: whether to remove views found in a design document that are not found in the list of ViewDefinition instances, default false.

callback: a callback function invoked when a design document gets updated; it is called before the doc has actually been saved back to the database.

func ToJSONCompatibleMap

func ToJSONCompatibleMap(obj interface{}) (map[string]interface{}, error)

ToJSONCompatibleMap converts a Document-embedded struct into a JSON-compatible map, e.g. anything that cannot be jsonified will be ignored silently.

type Database

type Database struct {
    // contains filtered or unexported fields
}

Database represents a CouchDB database instance.

func NewDatabase
func NewDatabase(urlStr string) (*Database, error)

NewDatabase returns a CouchDB database instance.

func NewDatabaseWithResource
func NewDatabaseWithResource(res *Resource) (*Database, error)

NewDatabaseWithResource returns a CouchDB database instance with resource obj.

func (d *Database) Available
func (d *Database) Available() error

Available returns error if the database is not good to go.

func (d *Database) Changes
func (d *Database) Changes(options url.Values) (map[string]interface{}, error)

Changes returns a sorted list of changes feed made to documents in the database.

func (d *Database) Cleanup
func (d *Database) Cleanup() error

Cleanup removes all view index files no longer required by CouchDB.

func (d *Database) Commit
func (d *Database) Commit() error

Commit flushes any recent changes to the specified database to disk. If the server is configured to delay commits or previous requests use the special "X-Couch-Full-Commit: false" header to disable immediate commits, this method can be used to ensure that non-commited changes are commited to physical storage.

func (d *Database) Compact
func (d *Database) Compact() error

Compact compacts the database by compressing the disk database file.

func (d *Database) Contains
func (d *Database) Contains(docid string) error

Contains returns true if the database contains a document with the specified ID.

func (d *Database) Copy
func (d *Database) Copy(srcID, destID, destRev string) (string, error)

Copy copies an existing document to a new or existing document.

func (d *Database) Delete
func (d *Database) Delete(docid string) error

Delete deletes the document with the specified ID.

func (d *Database) DeleteAttachment
func (d *Database) DeleteAttachment(doc map[string]interface{}, name string) error

DeleteAttachment deletes the specified attachment.

func (d *Database) DeleteDoc
func (d *Database) DeleteDoc(doc map[string]interface{}) error

DeleteDoc deletes the specified document

func (d *Database) DeleteIndex
func (d *Database) DeleteIndex(ddoc, name string) error

DeleteIndex deletes index in database.

func (d *Database) DocIDs
func (d *Database) DocIDs() ([]string, error)

DocIDs returns the IDs of all documents in database.

func (d *Database) Get
func (d *Database) Get(docid string, options url.Values) (map[string]interface{}, error)

Get returns the document with the specified ID.

func (d *Database) GetAttachment
func (d *Database) GetAttachment(doc map[string]interface{}, name string) ([]byte, error)

GetAttachment returns the file attachment associated with the document. The raw data is returned as a []byte.

func (d *Database) GetAttachmentID
func (d *Database) GetAttachmentID(docid, name string) ([]byte, error)

GetAttachmentID returns the file attachment associated with the document ID. The raw data is returned as []byte.

func (d *Database) GetIndex
func (d *Database) GetIndex() (map[string]*json.RawMessage, error)

GetIndex gets all indexes created in database.

func (d *Database) GetRevsLimit
func (d *Database) GetRevsLimit() (int, error)

GetRevsLimit gets the current revs_limit(revision limit) setting.

func (d *Database) GetSecurity
func (d *Database) GetSecurity() (map[string]interface{}, error)

GetSecurity returns the current security object from the given database.

func (d *Database) Info
func (d *Database) Info() (map[string]interface{}, error)

Info returns the information about the database.

func (*Database) IterView
func (d *Database) IterView(name string, batch int, wrapper func(Row) Row, options map[string]interface{}) (<-chan Row, error)

IterView returns a channel fetching rows in batches which iterates a row at a time(pagination).

name: the name of the view, for user-defined views use the format "design_docid/viewname", that is, the document ID of the design document and the name of the view, separated by a /.

wrapper: an optional function for processing the result rows after retrieved.

options: optional query parameters.

func (d *Database) Len
func (d *Database) Len() (int, error)

Len returns the number of documents stored in it.

func (*Database) List
func (d *Database) List(name, view string, options map[string]interface{}) (http.Header, []byte, error)

List formats a view using a server-side 'list' function.

name: the name of the list function in the format "designdoc/listname"

view: the name of the view in the format "designdoc/viewname"

options: optional query parameters

func (d *Database) Name
func (d *Database) Name() (string, error)

Name returns the name of database.

func (d *Database) Purge
func (d *Database) Purge(docs []map[string]interface{}) (map[string]interface{}, error)

Purge performs complete removing of the given documents.

func (d *Database) PutAttachment
func (d *Database) PutAttachment(doc map[string]interface{}, content []byte, name, mimeType string) error

PutAttachment uploads the supplied []byte as an attachment to the specified document. doc: the document that the attachment belongs to. Must have _id and _rev inside. content: the data to be attached to doc. name: name of attachment. mimeType: MIME type of content.

func (d *Database) PutIndex
func (d *Database) PutIndex(indexFields []string, ddoc, name string) (string, string, error)

PutIndex creates a new index in database. indexFields: a JSON array of field names following the sort syntax. ddoc: optional, name of the design document in which the index will be created. By default each index will be created in its own design document. Indexes can be grouped into design documents for efficiency. However a change to one index in a design document will invalidate all other indexes in the same document. name: optional, name of the index. A name generated automatically if not provided.

func (d *Database) Query
func (d *Database) Query(fields []string, selector string, sorts []string, limit, skip, index interface{}) ([]map[string]interface{}, error)

Query returns documents using a conditional selector statement in Golang.

selector: A filter string declaring which documents to return, formatted as a Golang statement.

fields: Specifying which fields to be returned, if passing nil the entire is returned, no automatic inclusion of _id or other metadata fields.

sorts: How to order the documents returned, formatted as ["desc(fieldName1)", "desc(fieldName2)"] or ["fieldNameA", "fieldNameB"] of which "asc" is used by default, passing nil to disable ordering.

limit: Maximum number of results returned, passing nil to use default value(25).

skip: Skip the first 'n' results, where 'n' is the number specified, passing nil for no-skip.

index: Instruct a query to use a specific index, specified either as "<design_document>" or ["<design_document>", "<index_name>"], passing nil to use primary index(_all_docs) by default.

Inner functions for selector syntax

nor(condexprs...) matches if none of the conditions in condexprs match($nor).

For example: nor(year == 1990, year == 1989, year == 1997) returns all documents whose year field not in 1989, 1990 and 1997.

all(field, array) matches an array value if it contains all the elements of the argument array($all).

For example: all(genre, []string{"Comedy", "Short"} returns all documents whose genre field contains "Comedy" and "Short".

any(field, condexpr) matches an array field with at least one element meets the specified condition($elemMatch).

For example: any(genre, genre == "Short" || genre == "Horror") returns all documents whose genre field contains "Short" or "Horror" or both.

exists(field, boolean) checks whether the field exists or not, regardless of its value($exists).

For example: exists(director, false) returns all documents who does not have a director field.

typeof(field, type) checks the document field's type, valid types are "null", "boolean", "number", "string", "array", "object"($type).

For example: typeof(genre, "array") returns all documents whose genre field is of array type.

in(field, array) the field must exist in the array provided($in).

For example: in(director, []string{"Mike Portnoy", "Vitali Kanevsky"}) returns all documents whose director field is "Mike Portnoy" or "Vitali Kanevsky".

nin(field, array) the document field must not exist in the array provided($nin).

For example: nin(year, []int{1990, 1992, 1998}) returns all documents whose year field is not in 1990, 1992 or 1998.

size(field, int) matches the length of an array field in a document($size).

For example: size(genre, 2) returns all documents whose genre field is of length 2.

mod(field, divisor, remainder) matches documents where field % divisor == remainder($mod).

For example: mod(year, 2, 1) returns all documents whose year field is an odd number.

regex(field, regexstr) a regular expression pattern to match against the document field.

For example: regex(title, "^A") returns all documents whose title is begin with an "A".

##Inner functions for sort syntax

asc(field) sorts the field in ascending order, this is the default option while desc(field) sorts the field in descending order.

func (d *Database) QueryJSON
func (d *Database) QueryJSON(query string) ([]map[string]interface{}, error)

QueryJSON returns documents using a declarative JSON querying syntax.

func (d *Database) Revisions
func (d *Database) Revisions(docid string, options url.Values) ([]map[string]interface{}, error)

Revisions returns all available revisions of the given document in reverse order, e.g. latest first.

func (d *Database) Save
func (d *Database) Save(doc map[string]interface{}, options url.Values) (string, string, error)

Save creates a new document or update an existing document. If doc has no _id the server will generate a random UUID and a new document will be created. Otherwise the doc's _id will be used to identify the document to create or update. Trying to update an existing document with an incorrect _rev will cause failure. NOTE It is recommended to avoid saving doc without _id and instead generate document ID on client side. To avoid such problems you can generate a UUID on the client side. GenerateUUID provides a simple, platform-independent implementation. You can also use other third-party packages instead. doc: the document to create or update.

func (d *Database) Set
func (d *Database) Set(docid string, doc map[string]interface{}) error

Set creates or updates a document with the specified ID.

func (d *Database) SetRevsLimit
func (d *Database) SetRevsLimit(limit int) error

SetRevsLimit sets the maximum number of document revisions that will be tracked by CouchDB.

func (d *Database) SetSecurity
func (d *Database) SetSecurity(securityDoc map[string]interface{}) error

SetSecurity sets the security object for the given database.

func (*Database) Show
func (d *Database) Show(name, docID string, params url.Values) (http.Header, []byte, error)

Show calls a server-side 'show' function.

name: the name of the show function in the format "designdoc/showname"

docID: optional document ID to pass to the show function

params: optional query parameters

func (d *Database) String
func (d *Database) String() string
func (d *Database) Update
func (d *Database) Update(docs []map[string]interface{}, options map[string]interface{}) ([]UpdateResult, error)

Update performs a bulk update or creation of the given documents in a single HTTP request. It returns a 3-tuple (id, rev, error)

func (*Database) UpdateDoc
func (d *Database) UpdateDoc(name, docID string, params url.Values) (http.Header, []byte, error)

UpdateDoc calls server-side update handler.

name: the name of the update handler function in the format "designdoc/updatename".

docID: optional document ID to pass to the show function

params: optional query parameters

func (*Database) View
func (d *Database) View(name string, wrapper func(Row) Row, options map[string]interface{}) (*ViewResults, error)

View executes a predefined design document view and returns the results.

name: the name of the view, for user-defined views use the format "design_docid/viewname", that is, the document ID of the design document and the name of the view, separated by a /.

wrapper: an optional function for processing the result rows after retrieved.

options: optional query parameters.

type Document

type Document struct {
    ID  string `json:"_id,omitempty"`  // for json only, call SetID/GetID instead
    Rev string `json:"_rev,omitempty"` // for json only, call GetRev instead
    // contains filtered or unexported fields
}

Document represents a document object in database.

func DocumentWithID
func DocumentWithID(id string) Document

DocumentWithID returns a new Document with ID.

func (*Document) GetID
func (d *Document) GetID() string

GetID returns the document ID.

func (*Document) GetRev
func (d *Document) GetRev() string

GetRev returns the document revision.

func (*Document) SetID
func (d *Document) SetID(id string) error

SetID sets ID for new document or return error.

func (*Document) SetRev
func (d *Document) SetRev(rev string)

SetRev sets revision for document.

type Resource

type Resource struct {
    // contains filtered or unexported fields
}

Resource handles all requests to CouchDB.

func NewResource
func NewResource(urlStr string, header http.Header) (*Resource, error)

NewResource returns a newly-created Resource instance.

func (r *Resource) Delete
func (r *Resource) Delete(path string, header http.Header, params url.Values) (http.Header, []byte, error)

Delete is a wrapper around http.Delete.

func (r *Resource) DeleteJSON
func (r *Resource) DeleteJSON(path string, header http.Header, params url.Values) (http.Header, []byte, error)

DeleteJSON issues a DELETE to the specified URL, with data returned as json.

func (r *Resource) Get
func (r *Resource) Get(path string, header http.Header, params url.Values) (http.Header, []byte, error)

Get is a wrapper around http.Get.

func (r *Resource) GetJSON
func (r *Resource) GetJSON(path string, header http.Header, params url.Values) (http.Header, []byte, error)

GetJSON issues a GET to the specified URL, with data returned as json.

func (r *Resource) Head
func (r *Resource) Head(path string, header http.Header, params url.Values) (http.Header, []byte, error)

Head is a wrapper around http.Head.

func (r *Resource) NewResourceWithURL
func (r *Resource) NewResourceWithURL(resStr string) (*Resource, error)

NewResourceWithURL returns newly created *Resource combined with resource string.

func (r *Resource) Post
func (r *Resource) Post(path string, header http.Header, body []byte, params url.Values) (http.Header, []byte, error)

Post is a wrapper around http.Post.

func (r *Resource) PostJSON
func (r *Resource) PostJSON(path string, header http.Header, body map[string]interface{}, params url.Values) (http.Header, []byte, error)

PostJSON issues a POST to the specified URL, with data returned as json.

func (r *Resource) Put
func (r *Resource) Put(path string, header http.Header, body []byte, params url.Values) (http.Header, []byte, error)

Put is a wrapper around http.Put.

func (r *Resource) PutJSON
func (r *Resource) PutJSON(path string, header http.Header, body map[string]interface{}, params url.Values) (http.Header, []byte, error)

PutJSON issues a PUT to the specified URL, with data returned as json.

type Row

type Row struct {
    ID  string
    Key interface{}
    Val interface{}
    Doc interface{}
    Err error
}

Row represents a row returned by database views.

func (Row) String
func (r Row) String() string

String returns a string representation for Row

type Server

type Server struct {
    // contains filtered or unexported fields
}

Server represents a CouchDB server instance.

func NewServer
func NewServer(urlStr string) (*Server, error)

NewServer creates a CouchDB server instance in address urlStr.

func NewServerNoFullCommit
func NewServerNoFullCommit(urlStr string) (*Server, error)

NewServerNoFullCommit creates a CouchDB server instance in address urlStr with X-Couch-Full-Commit disabled.

func (s *Server) ActiveTasks
func (s *Server) ActiveTasks() ([]interface{}, error)

ActiveTasks lists of running tasks.

func (s *Server) AddUser
func (s *Server) AddUser(name, password string, roles []string) (string, string, error)

AddUser adds regular user in authentication database. Returns id and rev of the registered user.

func (s *Server) Config
func (s *Server) Config(node string) (map[string]map[string]string, error)

Config returns the entire CouchDB server configuration as JSON structure.

func (s *Server) Contains
func (s *Server) Contains(name string) bool

Contains returns true if a db with given name exsited.

func (s *Server) Create
func (s *Server) Create(name string) (*Database, error)

Create returns a database instance with the given name, returns true if created, if database already existed, returns false, *Database will be nil if failed.

func (s *Server) DBs
func (s *Server) DBs() ([]string, error)

DBs returns a list of all the databases in the CouchDB server instance.

func (s *Server) Delete
func (s *Server) Delete(name string) error

Delete deletes a database with the given name. Return false if failed.

func (s *Server) Get
func (s *Server) Get(name string) (*Database, error)

Get gets a database instance with the given name. Return nil if failed.

func (s *Server) Len
func (s *Server) Len() (int, error)

Len returns the number of dbs in CouchDB server instance.

func (s *Server) Login
func (s *Server) Login(name, password string) (string, error)

Login regular user in CouchDB, returns authentication token.

func (s *Server) Logout
func (s *Server) Logout(token string) error

Logout regular user in CouchDB.

func (s *Server) Membership
func (s *Server) Membership() ([]string, []string, error)

Membership displays the nodes that are part of the cluster as clusterNodes. The field allNodes displays all nodes this node knows about, including the ones that are part of cluster.

func (s *Server) RemoveUser
func (s *Server) RemoveUser(name string) error

RemoveUser removes regular user in authentication database.

func (s *Server) Replicate
func (s *Server) Replicate(source, target string, options map[string]interface{}) (map[string]interface{}, error)

Replicate requests, configure or stop a replication operation.

func (s *Server) Stats
func (s *Server) Stats(node, entry string) (map[string]interface{}, error)

Stats returns a JSON object containing the statistics for the running server.

func (s *Server) String
func (s *Server) String() string
func (s *Server) UUIDs
func (s *Server) UUIDs(count int) ([]string, error)

UUIDs requests one or more Universally Unique Identifiers from the CouchDB instance. The response is a JSON object providing a list of UUIDs. count - Number of UUIDs to return. Default is 1.

func (s *Server) VerifyToken
func (s *Server) VerifyToken(token string) error

VerifyToken returns error if user's token is invalid.

func (s *Server) Version
func (s *Server) Version() (string, error)

Version returns the version info about CouchDB instance.

type UpdateResult

type UpdateResult struct {
    ID, Rev string
    Err     error
}

UpdateResult represents result of an update.

type ViewDefinition

type ViewDefinition struct {
    // contains filtered or unexported fields
}

ViewDefinition is a definition of view stored in a specific design document.

func NewViewDefinition
func NewViewDefinition(design, name, mapFun, reduceFun, language string, wrapper func(Row) Row, options map[string]interface{}) (*ViewDefinition, error)

NewViewDefinition returns a newly-created *ViewDefinition. design: the name of the design document.

name: the name of the view.

mapFun: the map function code.

reduceFun: the reduce function code(optional).

language: the name of the programming language used, default is javascript.

wrapper: an optional function for processing the result rows after retrieved.

options: view specific options.

func (*ViewDefinition) GetDoc
func (vd *ViewDefinition) GetDoc(db *Database) (map[string]interface{}, error)

GetDoc retrieves the design document corresponding to this view definition from the given database.

func (*ViewDefinition) Sync
func (vd *ViewDefinition) Sync(db *Database) ([]UpdateResult, error)

Sync ensures that the view stored in the database matches the view defined by this instance.

func (*ViewDefinition) View
func (vd *ViewDefinition) View(db *Database, options map[string]interface{}) (*ViewResults, error)

View executes the view definition in the given database.

type ViewField

type ViewField func() (*ViewDefinition, error)

ViewField represents a view definition value bound to Document.

func NewViewField
func NewViewField(design, name, mapFun, reduceFun, language string, wrapper func(Row) Row, options map[string]interface{}) ViewField

NewViewField returns a ViewField function. design: the name of the design document.

name: the name of the view.

mapFun: the map function code.

reduceFun: the reduce function code(optional).

language: the name of the programming language used, default is javascript.

wrapper: an optional function for processing the result rows after retrieved.

options: view specific options.

type ViewResults

type ViewResults struct {
    // contains filtered or unexported fields
}

ViewResults represents the results produced by design document views.

func (*ViewResults) Offset
func (vr *ViewResults) Offset() (int, error)

Offset returns offset of ViewResults

func (*ViewResults) Rows
func (vr *ViewResults) Rows() ([]Row, error)

Rows returns a slice of rows mapped (and reduced) by the view.

func (*ViewResults) TotalRows
func (vr *ViewResults) TotalRows() (int, error)

TotalRows returns total rows of ViewResults

func (*ViewResults) UpdateSeq
func (vr *ViewResults) UpdateSeq() (int, error)

UpdateSeq returns update sequence of ViewResults

Documentation

Overview

Package couchdb provides components to work with CouchDB 2.x with Go.

Resource is the low-level wrapper functions of HTTP methods used for communicating with CouchDB Server.

Server contains all the functions to work with CouchDB server, including some basic functions to facilitate the basic user management provided by it.

Database contains all the functions to work with CouchDB database, such as documents manipulating and querying.

ViewResults represents the results produced by design document views. When calling any of its functions like Offset(), TotalRows(), UpdateSeq() or Rows(), it will perform a query on views on server side, and returns results as slice of Row

ViewDefinition is a definition of view stored in a specific design document, you can define your own map-reduce functions and Sync with the database.

Document represents a document object in database. All struct that can be mapped into CouchDB document must have it embedded. For example: 

type User struct {
  Name string `json:"name"`
  Age int `json:"age"`
  Document
}
user := User{"Mike", 18}
anotherUser := User{}

Then you can call Store(db, &user) to store it into CouchDB or Load(db, user.GetID(), &anotherUser) to get the data from database.

ViewField represents a view definition value bound to Document.

Index

Constants

View Source 
const (
	// DefaultBaseURL is the default address of CouchDB server.
	DefaultBaseURL = "http://localhost:5984"
)

Variables

View Source 
var (
	// ErrBatchValue for invalid batch parameter of IterView
	ErrBatchValue = errors.New("batch must be 1 or more")
	// ErrLimitValue for invalid limit parameter of IterView
	ErrLimitValue = errors.New("limit must be 1 or more")
)
View Source 
var (
	// ErrSetID for setting ID to document which already has one.
	ErrSetID = errors.New("id can only be set on new documents")
	// ErrNotStruct for not a struct value
	ErrNotStruct = errors.New("value not of struct type")
	// ErrNotDocumentEmbedded for not a document-embedded value
	ErrNotDocumentEmbedded = errors.New("value not Document-embedded")
)
View Source 
var (

	// ErrNotModified for HTTP status code 304
	ErrNotModified = errors.New("status 304 - not modified")
	// ErrBadRequest for HTTP status code 400
	ErrBadRequest = errors.New("status 400 - bad request")
	// ErrUnauthorized for HTTP status code 401
	ErrUnauthorized = errors.New("status 401 - unauthorized")
	// ErrForbidden for HTTP status code 403
	ErrForbidden = errors.New("status 403 - forbidden")
	// ErrNotFound for HTTP status code 404
	ErrNotFound = errors.New("status 404 - not found")
	// ErrResourceNotAllowed for HTTP status code 405
	ErrResourceNotAllowed = errors.New("status 405 - resource not allowed")
	// ErrNotAcceptable for HTTP status code 406
	ErrNotAcceptable = errors.New("status 406 - not acceptable")
	// ErrConflict for HTTP status code 409
	ErrConflict = errors.New("status 409 - conflict")
	// ErrPreconditionFailed for HTTP status code 412
	ErrPreconditionFailed = errors.New("status 412 - precondition failed")
	// ErrBadContentType for HTTP status code 415
	ErrBadContentType = errors.New("status 415 - bad content type")
	// ErrRequestRangeNotSatisfiable for HTTP status code 416
	ErrRequestRangeNotSatisfiable = errors.New("status 416 - requested range not satisfiable")
	// ErrExpectationFailed for HTTP status code 417
	ErrExpectationFailed = errors.New("status 417 - expectation failed")
	// ErrInternalServerError for HTTP status code 500
	ErrInternalServerError = errors.New("status 500 - internal server error")
)

Functions

func FromJSONCompatibleMap 

func FromJSONCompatibleMap(obj interface{}, docMap map[string]interface{}) error

FromJSONCompatibleMap constructs a Document-embedded struct from a JSON-compatible map.

func GenerateUUID 

func GenerateUUID() string

GenerateUUID returns a random 128-bit UUID

func Load 

func Load(db *Database, docID string, obj interface{}) error

Load loads the document in specified database.

func Store 

func Store(db *Database, obj interface{}) error

Store stores the document in specified database. obj: a Document-embedded struct value, its id and rev will be updated after stored, so caller must pass a pointer value.

func ToJSONCompatibleMap 

func ToJSONCompatibleMap(obj interface{}) (map[string]interface{}, error)

ToJSONCompatibleMap converts a Document-embedded struct into a JSON-compatible map, e.g. anything that cannot be jsonified will be ignored silently.

Types

type Database 

type Database struct {
	// contains filtered or unexported fields
}

Database represents a CouchDB database instance.

func NewDatabase 

func NewDatabase(urlStr string) (*Database, error)

NewDatabase returns a CouchDB database instance.

func NewDatabaseWithResource 

func NewDatabaseWithResource(res *Resource) (*Database, error)

NewDatabaseWithResource returns a CouchDB database instance with resource obj.

func (*Database) Available 

func (d *Database) Available() error

Available returns error if the database is not good to go.

func (*Database) Changes 

func (d *Database) Changes(options url.Values) (map[string]interface{}, error)

Changes returns a sorted list of changes feed made to documents in the database.

func (*Database) Cleanup 

func (d *Database) Cleanup() error

Cleanup removes all view index files no longer required by CouchDB.

func (*Database) Commit 

func (d *Database) Commit() error

Commit flushes any recent changes to the specified database to disk. If the server is configured to delay commits or previous requests use the special "X-Couch-Full-Commit: false" header to disable immediate commits, this method can be used to ensure that non-commited changes are commited to physical storage.

func (*Database) Compact 

func (d *Database) Compact() error

Compact compacts the database by compressing the disk database file.

func (*Database) Contains 

func (d *Database) Contains(docid string) error

Contains returns true if the database contains a document with the specified ID.

func (*Database) Copy 

func (d *Database) Copy(srcID, destID, destRev string) (string, error)

Copy copies an existing document to a new or existing document.

func (*Database) Delete 

func (d *Database) Delete(docid string) error

Delete deletes the document with the specified ID.

func (*Database) DeleteAttachment 

func (d *Database) DeleteAttachment(doc map[string]interface{}, name string) error

DeleteAttachment deletes the specified attachment

func (*Database) DeleteDoc 

func (d *Database) DeleteDoc(doc map[string]interface{}) error

DeleteDoc deletes the specified document

func (*Database) DeleteIndex 

func (d *Database) DeleteIndex(ddoc, name string) error

DeleteIndex deletes index in database.

func (*Database) DocIDs 

func (d *Database) DocIDs() ([]string, error)

DocIDs returns the IDs of all documents in database.

func (*Database) Get 

func (d *Database) Get(docid string, options url.Values) (map[string]interface{}, error)

Get returns the document with the specified ID.

func (*Database) GetAttachment 

func (d *Database) GetAttachment(doc map[string]interface{}, name string) ([]byte, error)

GetAttachment returns the file attachment associated with the document. The raw data is returned as a []byte.

func (*Database) GetAttachmentID 

func (d *Database) GetAttachmentID(docid, name string) ([]byte, error)

GetAttachmentID returns the file attachment associated with the document ID. The raw data is returned as []byte.

func (*Database) GetIndex 

func (d *Database) GetIndex() (map[string]*json.RawMessage, error)

GetIndex gets all indexes created in database.

func (*Database) GetRevsLimit 

func (d *Database) GetRevsLimit() (int, error)

GetRevsLimit gets the current revs_limit(revision limit) setting.

func (*Database) GetSecurity 

func (d *Database) GetSecurity() (map[string]interface{}, error)

GetSecurity returns the current security object from the given database.

func (*Database) Info 

func (d *Database) Info(ddoc string) (map[string]interface{}, error)

Info returns the information about the database or design document

func (*Database) IterView 

func (d *Database) IterView(name string, batch int, wrapper func(Row) Row, options map[string]interface{}) (<-chan Row, error)

IterView returns a channel fetching rows in batches which iterates a row at a time(pagination).

name: the name of the view, for user-defined views use the format "design_docid/viewname", that is, the document ID of the design document and the name of the view, separated by a /.

wrapper: an optional function for processing the result rows after retrieved.

options: optional query parameters.

func (*Database) Len 

func (d *Database) Len() (int, error)

Len returns the number of documents stored in it.

func (*Database) List 

func (d *Database) List(name, view string, options map[string]interface{}) (http.Header, []byte, error)

List formats a view using a server-side 'list' function.

name: the name of the list function in the format "designdoc/listname"

view: the name of the view in the format "designdoc/viewname"

options: optional query parameters

func (*Database) Name 

func (d *Database) Name() (string, error)

Name returns the name of database.

func (*Database) Purge 

func (d *Database) Purge(docs []map[string]interface{}) (map[string]interface{}, error)

Purge performs complete removing of the given documents.

func (*Database) PutAttachment 

func (d *Database) PutAttachment(doc map[string]interface{}, content []byte, name, mimeType string) error

PutAttachment uploads the supplied []byte as an attachment to the specified document. doc: the document that the attachment belongs to. Must have _id and _rev inside. content: the data to be attached to doc. name: name of attachment. mimeType: MIME type of content.

func (*Database) PutIndex 

func (d *Database) PutIndex(indexFields []string, ddoc, name string) (string, string, error)

PutIndex creates a new index in database.

indexFields: a JSON array of field names following the sort syntax.

ddoc: optional, name of the design document in which the index will be created. By default each index will be created in its own design document. Indexes can be grouped into design documents for efficiency. However a change to one index in a design document will invalidate all other indexes in the same document.

name: optional, name of the index. A name generated automatically if not provided.

func (*Database) Query 

func (d *Database) Query(fields []string, selector string, sorts []string, limit, skip, index interface{}) ([]map[string]interface{}, error)

Query returns documents using a conditional selector statement in Golang.

selector: A filter string declaring which documents to return, formatted as a Golang statement.

fields: Specifying which fields to be returned, if passing nil the entire is returned, no automatic inclusion of _id or other metadata fields.

sorts: How to order the documents returned, formatted as ["desc(fieldName1)", "desc(fieldName2)"] or ["fieldNameA", "fieldNameB"] of which "asc" is used by default, passing nil to disable ordering.

limit: Maximum number of results returned, passing nil to use default value(25).

skip: Skip the first 'n' results, where 'n' is the number specified, passing nil for no-skip.

index: Instruct a query to use a specific index, specified either as "<design_document>" or ["<design_document>", "<index_name>"], passing nil to use primary index(_all_docs) by default.

Inner functions for selector syntax

nor(condexprs...) matches if none of the conditions in condexprs match($nor).

For example: nor(year == 1990, year == 1989, year == 1997) returns all documents whose year field not in 1989, 1990 and 1997.

all(field, array) matches an array value if it contains all the elements of the argument array($all).

For example: all(genre, []string{"Comedy", "Short"} returns all documents whose genre field contains "Comedy" and "Short".

any(field, condexpr) matches an array field with at least one element meets the specified condition($elemMatch).

For example: any(genre, genre == "Short" || genre == "Horror") returns all documents whose genre field contains "Short" or "Horror" or both.

exists(field, boolean) checks whether the field exists or not, regardless of its value($exists).

For example: exists(director, false) returns all documents who does not have a director field.

typeof(field, type) checks the document field's type, valid types are "null", "boolean", "number", "string", "array", "object"($type).

For example: typeof(genre, "array") returns all documents whose genre field is of array type.

in(field, array) the field must exist in the array provided($in).

For example: in(director, []string{"Mike Portnoy", "Vitali Kanevsky"}) returns all documents whose director field is "Mike Portnoy" or "Vitali Kanevsky".

nin(field, array) the document field must not exist in the array provided($nin).

For example: nin(year, []int{1990, 1992, 1998}) returns all documents whose year field is not in 1990, 1992 or 1998.

size(field, int) matches the length of an array field in a document($size).

For example: size(genre, 2) returns all documents whose genre field is of length 2.

mod(field, divisor, remainder) matches documents where field % divisor == remainder($mod).

For example: mod(year, 2, 1) returns all documents whose year field is an odd number.

regex(field, regexstr) a regular expression pattern to match against the document field.

For example: regex(title, "^A") returns all documents whose title is begin with an "A".

Inner functions for sort syntax

asc(field) sorts the field in ascending order, this is the default option while desc(field) sorts the field in descending order.

func (*Database) QueryJSON 

func (d *Database) QueryJSON(query string) ([]map[string]interface{}, error)

QueryJSON returns documents using a declarative JSON querying syntax.

func (*Database) Revisions 

func (d *Database) Revisions(docid string, options url.Values) ([]map[string]interface{}, error)

Revisions returns all available revisions of the given document in reverse order, e.g. latest first.

func (*Database) Save 

func (d *Database) Save(doc map[string]interface{}, options url.Values) (string, string, error)

Save creates a new document or update an existing document. If doc has no _id the server will generate a random UUID and a new document will be created. Otherwise the doc's _id will be used to identify the document to create or update. Trying to update an existing document with an incorrect _rev will cause failure. *NOTE* It is recommended to avoid saving doc without _id and instead generate document ID on client side. To avoid such problems you can generate a UUID on the client side. GenerateUUID provides a simple, platform-independent implementation. You can also use other third-party packages instead. doc: the document to create or update.

func (*Database) Set 

func (d *Database) Set(docid string, doc map[string]interface{}) error

Set creates or updates a document with the specified ID.

func (*Database) SetRevsLimit 

func (d *Database) SetRevsLimit(limit int) error

SetRevsLimit sets the maximum number of document revisions that will be tracked by CouchDB.

func (*Database) SetSecurity 

func (d *Database) SetSecurity(securityDoc map[string]interface{}) error

SetSecurity sets the security object for the given database.

func (*Database) Show 

func (d *Database) Show(name, docID string, params url.Values) (http.Header, []byte, error)

Show calls a server-side 'show' function.

name: the name of the show function in the format "designdoc/showname"

docID: optional document ID to pass to the show function

params: optional query parameters

func (*Database) String 

func (d *Database) String() string

func (*Database) Update 

func (d *Database) Update(docs []map[string]interface{}, options map[string]interface{}) ([]UpdateResult, error)

Update performs a bulk update or creation of the given documents in a single HTTP request. It returns a 3-tuple (id, rev, error)

func (*Database) UpdateDoc 

func (d *Database) UpdateDoc(name, docID string, params url.Values) (http.Header, []byte, error)

UpdateDoc calls server-side update handler.

name: the name of the update handler function in the format "designdoc/updatename".

docID: optional document ID to pass to the show function

params: optional query parameters

func (*Database) View 

func (d *Database) View(name string, wrapper func(Row) Row, options map[string]interface{}) (*ViewResults, error)

View executes a predefined design document view and returns the results.

name: the name of the view, for user-defined views use the format "design_docid/viewname", that is, the document ID of the design document and the name of the view, separated by a /.

wrapper: an optional function for processing the result rows after retrieved.

options: optional query parameters.

type Document 

type Document struct {
	ID  string `json:"_id,omitempty"`  // for json only, call SetID/GetID instead
	Rev string `json:"_rev,omitempty"` // for json only, call GetRev instead
	// contains filtered or unexported fields
}

Document represents a document object in database.

func DocumentWithID 

func DocumentWithID(id string) Document

DocumentWithID returns a new Document with ID.

func (*Document) GetID 

func (d *Document) GetID() string

GetID returns the document ID.

func (*Document) GetRev 

func (d *Document) GetRev() string

GetRev returns the document revision.

func (*Document) SetID 

func (d *Document) SetID(id string) error

SetID sets ID for new document or return error.

func (*Document) SetRev 

func (d *Document) SetRev(rev string)

SetRev sets revision for document.

type Resource 

type Resource struct {
	// contains filtered or unexported fields
}

Resource handles all requests to CouchDB

func NewResource 

func NewResource(urlStr string, header http.Header) (*Resource, error)

NewResource returns a newly-created Resource instance

func (*Resource) Delete 

func (r *Resource) Delete(path string, header http.Header, params url.Values) (http.Header, []byte, error)

Delete is a wrapper around http.Delete

func (*Resource) DeleteJSON 

func (r *Resource) DeleteJSON(path string, header http.Header, params url.Values) (http.Header, []byte, error)

DeleteJSON issues a DELETE to the specified URL, with data returned as json

func (*Resource) Get 

func (r *Resource) Get(path string, header http.Header, params url.Values) (http.Header, []byte, error)

Get is a wrapper around http.Get

func (*Resource) GetJSON 

func (r *Resource) GetJSON(path string, header http.Header, params url.Values) (http.Header, []byte, error)

GetJSON issues a GET to the specified URL, with data returned as json

func (*Resource) Head 

func (r *Resource) Head(path string, header http.Header, params url.Values) (http.Header, []byte, error)

Head is a wrapper around http.Head

func (*Resource) NewResourceWithURL 

func (r *Resource) NewResourceWithURL(resStr string) (*Resource, error)

NewResourceWithURL returns newly created *Resource combined with resource string.

func (*Resource) Post 

func (r *Resource) Post(path string, header http.Header, body []byte, params url.Values) (http.Header, []byte, error)

Post is a wrapper around http.Post

func (*Resource) PostJSON 

func (r *Resource) PostJSON(path string, header http.Header, body map[string]interface{}, params url.Values) (http.Header, []byte, error)

PostJSON issues a POST to the specified URL, with data returned as json

func (*Resource) Put 

func (r *Resource) Put(path string, header http.Header, body []byte, params url.Values) (http.Header, []byte, error)

Put is a wrapper around http.Put

func (*Resource) PutJSON 

func (r *Resource) PutJSON(path string, header http.Header, body map[string]interface{}, params url.Values) (http.Header, []byte, error)

PutJSON issues a PUT to the specified URL, with data returned as json

type Row 

type Row struct {
	ID  string
	Key interface{}
	Val interface{}
	Doc interface{}
	Err error
}

Row represents a row returned by database views.

func (Row) String 

func (r Row) String() string

String returns a string representation for Row

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server represents a CouchDB server instance.

func NewServer 

func NewServer(urlStr string) (*Server, error)

NewServer creates a CouchDB server instance in address urlStr.

func NewServerNoFullCommit 

func NewServerNoFullCommit(urlStr string) (*Server, error)

NewServerNoFullCommit creates a CouchDB server instance in address urlStr with X-Couch-Full-Commit disabled.

func (*Server) ActiveTasks 

func (s *Server) ActiveTasks() ([]interface{}, error)

ActiveTasks lists of running tasks.

func (*Server) AddUser 

func (s *Server) AddUser(name, password string, roles []string) (string, string, error)

AddUser adds regular user in authentication database. Returns id and rev of the registered user.

func (*Server) Config 

func (s *Server) Config(node string) (map[string]map[string]string, error)

Config returns the entire CouchDB server configuration as JSON structure.

func (*Server) Contains 

func (s *Server) Contains(name string) bool

Contains returns true if a db with given name exsited.

func (*Server) Create 

func (s *Server) Create(name string) (*Database, error)

Create returns a database instance with the given name, returns true if created, if database already existed, returns false, *Database will be nil if failed.

func (*Server) DBs 

func (s *Server) DBs() ([]string, error)

DBs returns a list of all the databases in the CouchDB server instance.

func (*Server) Delete 

func (s *Server) Delete(name string) error

Delete deletes a database with the given name. Return false if failed.

func (*Server) Get 

func (s *Server) Get(name string) (*Database, error)

Get gets a database instance with the given name. Return nil if failed.

func (*Server) Len 

func (s *Server) Len() (int, error)

Len returns the number of dbs in CouchDB server instance.

func (*Server) Login 

func (s *Server) Login(name, password string) (string, error)

Login regular user in CouchDB, returns authentication token.

func (*Server) Logout 

func (s *Server) Logout(token string) error

Logout regular user in CouchDB

func (*Server) Membership 

func (s *Server) Membership() ([]string, []string, error)

Membership displays the nodes that are part of the cluster as clusterNodes. The field allNodes displays all nodes this node knows about, including the ones that are part of cluster.

func (*Server) RemoveUser 

func (s *Server) RemoveUser(name string) error

RemoveUser removes regular user in authentication database.

func (*Server) Replicate 

func (s *Server) Replicate(source, target string, options map[string]interface{}) (map[string]interface{}, error)

Replicate requests, configure or stop a replication operation.

func (*Server) Stats 

func (s *Server) Stats(node, entry string) (map[string]interface{}, error)

Stats returns a JSON object containing the statistics for the running server.

func (*Server) String 

func (s *Server) String() string

func (*Server) UUIDs 

func (s *Server) UUIDs(count int) ([]string, error)

UUIDs requests one or more Universally Unique Identifiers from the CouchDB instance. The response is a JSON object providing a list of UUIDs. count - Number of UUIDs to return. Default is 1.

func (*Server) VerifyToken 

func (s *Server) VerifyToken(token string) error

VerifyToken returns error if user's token is invalid.

func (*Server) Version 

func (s *Server) Version() (string, error)

Version returns the version info about CouchDB instance.

type UpdateResult 

type UpdateResult struct {
	ID, Rev string
	Err     error
}

UpdateResult represents result of an update.

func SyncMany 

func SyncMany(db *Database, viewDefns []*ViewDefinition, removeMissing bool, callback func(map[string]interface{})) ([]UpdateResult, error)

SyncMany ensures that the views stored in the database match the views defined by the corresponding view definitions. This function might update more than one design document. This is done using CouchDB's bulk update to ensure atomicity of the opeation. db: the corresponding database.

viewDefns: a sequence of *ViewDefinition instances.

removeMissing: whether to remove views found in a design document that are not found in the list of ViewDefinition instances, default false.

callback: a callback function invoked when a design document gets updated; it is called before the doc has actually been saved back to the database.

type ViewDefinition 

type ViewDefinition struct {
	// contains filtered or unexported fields
}

ViewDefinition is a definition of view stored in a specific design document.

func NewViewDefinition 

func NewViewDefinition(design, name, mapFun, reduceFun, language string, wrapper func(Row) Row, options map[string]interface{}) (*ViewDefinition, error)

NewViewDefinition returns a newly-created *ViewDefinition. design: the name of the design document.

name: the name of the view.

mapFun: the map function code.

reduceFun: the reduce function code(optional).

language: the name of the programming language used, default is javascript.

wrapper: an optional function for processing the result rows after retrieved.

options: view specific options.

func (*ViewDefinition) GetDoc 

func (vd *ViewDefinition) GetDoc(db *Database) (map[string]interface{}, error)

GetDoc retrieves the design document corresponding to this view definition from the given database.

func (*ViewDefinition) Sync 

func (vd *ViewDefinition) Sync(db *Database) ([]UpdateResult, error)

Sync ensures that the view stored in the database matches the view defined by this instance.

func (*ViewDefinition) View 

func (vd *ViewDefinition) View(db *Database, options map[string]interface{}) (*ViewResults, error)

View executes the view definition in the given database.

type ViewField 

type ViewField func() (*ViewDefinition, error)

ViewField represents a view definition value bound to Document.

func NewViewField 

func NewViewField(design, name, mapFun, reduceFun, language string, wrapper func(Row) Row, options map[string]interface{}) ViewField

NewViewField returns a ViewField function. design: the name of the design document.

name: the name of the view.

mapFun: the map function code.

reduceFun: the reduce function code(optional).

language: the name of the programming language used, default is javascript.

wrapper: an optional function for processing the result rows after retrieved.

options: view specific options.

type ViewResults 

type ViewResults struct {
	// contains filtered or unexported fields
}

ViewResults represents the results produced by design document views.

func (*ViewResults) Offset 

func (vr *ViewResults) Offset() (int, error)

Offset returns offset of ViewResults

func (*ViewResults) Rows 

func (vr *ViewResults) Rows() ([]Row, error)

Rows returns a slice of rows mapped (and reduced) by the view.

func (*ViewResults) TotalRows 

func (vr *ViewResults) TotalRows() (int, error)

TotalRows returns total rows of ViewResults

func (*ViewResults) UpdateSeq 

func (vr *ViewResults) UpdateSeq() (int, error)

UpdateSeq returns update sequence of ViewResults

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.