go-couchdb: github.com/fjl/go-couchdb Index | Files | Directories

package couchdb

import "github.com/fjl/go-couchdb"

Package couchdb implements wrappers for the CouchDB HTTP API.

Unless otherwise noted, all functions in this package can be called from more than one goroutine at the same time.

Index

Package Files

attachments.go auth.go couchdb.go feeds.go http.go

func Conflict Uses

func Conflict(err error) bool

Conflict checks whether the given error is a DatabaseError with StatusCode == 409.

func ErrorStatus Uses

func ErrorStatus(err error, statusCode int) bool

ErrorStatus checks whether the given error is a DatabaseError with a matching statusCode.

func NotFound Uses

func NotFound(err error) bool

NotFound checks whether the given errors is a DatabaseError with StatusCode == 404. This is useful for conditional creation of databases and documents.

func Unauthorized Uses

func Unauthorized(err error) bool

Unauthorized checks whether the given error is a DatabaseError with StatusCode == 401.

type Attachment Uses

type Attachment struct {
    Name string    // Filename
    Type string    // MIME type of the Body
    MD5  []byte    // MD5 checksum of the Body
    Body io.Reader // The body itself
}

Attachment represents document attachments.

type Auth Uses

type Auth interface {
    // AddAuth should add authentication information (e.g. headers)
    // to the given HTTP request.
    AddAuth(*http.Request)
}

Auth is implemented by HTTP authentication mechanisms.

func BasicAuth Uses

func BasicAuth(username, password string) Auth

BasicAuth returns an Auth that performs HTTP Basic Authentication.

func ProxyAuth Uses

func ProxyAuth(username string, roles []string, secret string) Auth

ProxyAuth returns an Auth that performs CouchDB proxy authentication. Please consult the CouchDB documentation for more information on proxy authentication:

http://docs.couchdb.org/en/latest/api/server/authn.html?highlight=proxy#proxy-authentication

type ChangesFeed Uses

type ChangesFeed struct {
    // DB is the database. Since all events in a _changes feed
    // belong to the same database, this field is always equivalent to the
    // database from the DB.Changes call that created the feed object
    DB  *DB `json:"-"`

    // ID is the document ID of the current event.
    ID  string `json:"id"`

    // Deleted is true when the event represents a deleted document.
    Deleted bool `json:"deleted"`

    // Seq is the database update sequence number of the current event.
    // After all items have been processed, set to the last_seq value sent
    // by CouchDB.
    Seq int64 `json:"seq"`

    // Changes is the list of the document's leaf revisions.
    Changes []struct {
        Rev string `json:"rev"`
    }   `json:"changes"`

    // The document. This is populated only if the feed option
    // "include_docs" is true.
    Doc json.RawMessage `json:"doc"`
    // contains filtered or unexported fields
}

ChangesFeed is an iterator for the _changes feed of a database. On each call to the Next method, the event fields are updated for the current event. Next is designed to be used in a for loop:

    feed, err := client.Changes("db", nil)
    ...
    for feed.Next() {
	       fmt.Printf("changed: %s", feed.ID)
    }
    err = feed.Err()
    ...

func (*ChangesFeed) Close Uses

func (f *ChangesFeed) Close() error

Close terminates the connection of the feed. If Next returns false, the feed has already been closed.

func (*ChangesFeed) Err Uses

func (f *ChangesFeed) Err() error

Err returns the last error that occurred during iteration.

func (*ChangesFeed) Next Uses

func (f *ChangesFeed) Next() bool

Next decodes the next event. It returns false when the feeds end has been reached or an error has occurred.

type Client Uses

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

Client represents a remote CouchDB server.

func NewClient Uses

func NewClient(rawurl string, rt http.RoundTripper) (*Client, error)

NewClient creates a new client object.

If rawurl contains credentials, the client will authenticate using HTTP Basic Authentication. If rawurl has a query string, it is ignored.

The second argument can be nil to use http.Transport, which should be good enough in most cases.

func (*Client) AllDBs Uses

func (c *Client) AllDBs() (names []string, err error)

AllDBs returns the names of all existing databases.

func (*Client) CreateDB Uses

func (c *Client) CreateDB(name string) (*DB, error)

CreateDB creates a new database. The request will fail with status "412 Precondition Failed" if the database already exists. A valid DB object is returned in all cases, even if the request fails.

func (*Client) DB Uses

func (c *Client) DB(name string) *DB

DB creates a database object. The database inherits the authentication and http.RoundTripper of the client. The database's actual existence is not verified.

func (*Client) DBUpdates Uses

func (c *Client) DBUpdates(options Options) (*DBUpdatesFeed, error)

DBUpdates opens the _db_updates feed. For the possible options, please see the CouchDB documentation. Pleas note that the "feed" option is currently always set to "continuous".

http://docs.couchdb.org/en/latest/api/server/common.html#db-updates

func (*Client) DeleteDB Uses

func (c *Client) DeleteDB(name string) error

DeleteDB deletes an existing database.

func (*Client) EnsureDB Uses

func (c *Client) EnsureDB(name string) (*DB, error)

EnsureDB ensures that a database with the given name exists.

func (*Client) Ping Uses

func (c *Client) Ping() error

Ping can be used to check whether a server is alive. It sends an HTTP HEAD request to the server's URL.

func (*Client) SetAuth Uses

func (c *Client) SetAuth(a Auth)

SetAuth sets the authentication mechanism used by the client. Use SetAuth(nil) to unset any mechanism that might be in use. In order to verify the credentials against the server, issue any request after the call the SetAuth.

func (*Client) URL Uses

func (c *Client) URL() string

URL returns the URL prefix of the server. The url will not contain a trailing '/'.

type DB Uses

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

DB represents a remote CouchDB database.

func (*DB) AllDocs Uses

func (db *DB) AllDocs(result interface{}, opts Options) error

AllDocs invokes the _all_docs view of a database.

The output of the query is unmarshalled into the given result. The format of the result depends on the options. Please refer to the CouchDB HTTP API documentation for all the possible options that can be set.

http://docs.couchdb.org/en/latest/api/database/bulk-api.html#db-all-docs

func (*DB) Attachment Uses

func (db *DB) Attachment(docid, name, rev string) (*Attachment, error)

Attachment retrieves an attachment. The rev argument can be left empty to retrieve the latest revision. The caller is responsible for closing the attachment's Body if the returned error is nil.

func (*DB) AttachmentMeta Uses

func (db *DB) AttachmentMeta(docid, name, rev string) (*Attachment, error)

AttachmentMeta requests attachment metadata. The rev argument can be left empty to retrieve the latest revision. The returned attachment's Body is always nil.

func (*DB) Changes Uses

func (db *DB) Changes(options Options) (*ChangesFeed, error)

Changes opens the _changes feed of a database. This feed receives an event whenever a document is created, updated or deleted.

The implementation supports both poll-style and continuous feeds. The default feed mode is "normal", which retrieves changes up to some point and then closes the feed. If you want a never-ending feed, set the "feed" option to "continuous":

feed, err := client.Changes("db", couchdb.Options{"feed": "continuous"})

There are many other options that allow you to customize what the feed returns. For information on all of them, see the official CouchDB documentation:

http://docs.couchdb.org/en/latest/api/database/changes.html#db-changes

func (*DB) Delete Uses

func (db *DB) Delete(id, rev string) (newrev string, err error)

Delete marks a document revision as deleted.

func (*DB) DeleteAttachment Uses

func (db *DB) DeleteAttachment(docid, name, rev string) (newrev string, err error)

DeleteAttachment removes an attachment.

func (*DB) Get Uses

func (db *DB) Get(id string, doc interface{}, opts Options) error

Get retrieves a document from the given database. The document is unmarshalled into the given object. Some fields (like _conflicts) will only be returned if the options require it. Please refer to the CouchDB HTTP API documentation for more information.

http://docs.couchdb.org/en/latest/api/document/common.html?highlight=doc#get--db-docid

func (*DB) Name Uses

func (db *DB) Name() string

Name returns the name of a database.

func (*DB) Put Uses

func (db *DB) Put(id string, doc interface{}, rev string) (newrev string, err error)

Put stores a document into the given database.

func (*DB) PutAttachment Uses

func (db *DB) PutAttachment(docid string, att *Attachment, rev string) (newrev string, err error)

PutAttachment creates or updates an attachment. To create an attachment on a non-existing document, pass an empty rev.

func (*DB) PutSecurity Uses

func (db *DB) PutSecurity(secobj *Security) error

PutSecurity sets the database security object.

func (*DB) Rev Uses

func (db *DB) Rev(id string) (string, error)

Rev fetches the current revision of a document. It is faster than an equivalent Get request because no body has to be parsed.

func (*DB) Security Uses

func (db *DB) Security() (*Security, error)

Security retrieves the security object of a database.

func (*DB) View Uses

func (db *DB) View(ddoc, view string, result interface{}, opts Options) error

View invokes a view. The ddoc parameter must be the full name of the design document containing the view definition, including the _design/ prefix.

The output of the query is unmarshalled into the given result. The format of the result depends on the options. Please refer to the CouchDB HTTP API documentation for all the possible options that can be set.

http://docs.couchdb.org/en/latest/api/ddoc/views.html

type DBUpdatesFeed Uses

type DBUpdatesFeed struct {
    Event string `json:"type"`    // "created" | "updated" | "deleted"
    OK    bool   `json:"ok"`      // Event operation status
    DB    string `json:"db_name"` // Event database name
    // contains filtered or unexported fields
}

DBUpdatesFeed is an iterator for the _db_updates feed. This feed receives an event whenever any database is created, updated or deleted. On each call to the Next method, the event fields are updated for the current event.

    feed, err := client.DbUpdates(nil)
    ...
    for feed.Next() {
	       fmt.Printf("changed: %s %s", feed.Event, feed.Db)
    }
    err = feed.Err()
    ...

func (*DBUpdatesFeed) Close Uses

func (f *DBUpdatesFeed) Close() error

Close terminates the connection of a feed.

func (*DBUpdatesFeed) Err Uses

func (f *DBUpdatesFeed) Err() error

Err returns the last error that occurred during iteration.

func (*DBUpdatesFeed) Next Uses

func (f *DBUpdatesFeed) Next() bool

Next decodes the next event in a _db_updates feed. It returns false when the feeds end has been reached or an error has occurred.

type Error Uses

type Error struct {
    Method     string // HTTP method of the request
    URL        string // HTTP URL of the request
    StatusCode int    // HTTP status code of the response

    // These two fields will be empty for HEAD requests.
    ErrorCode string // Error reason provided by CouchDB
    Reason    string // Error message provided by CouchDB
}

Error represents API-level errors, reported by CouchDB as

{"error": <ErrorCode>, "reason": <Reason>}

func (*Error) Error Uses

func (e *Error) Error() string

type Members Uses

type Members struct {
    Names []string `json:"names,omitempty"`
    Roles []string `json:"roles,omitempty"`
}

Members represents member lists in database security objects.

type Options Uses

type Options map[string]interface{}

Options represents CouchDB query string parameters.

type Security Uses

type Security struct {
    Admins  Members `json:"admins"`
    Members Members `json:"members"`
}

Security represents database security objects.

Directories

PathSynopsis
couchappPackage couchapp implements a mapping from files to CouchDB documents.
couchdaemonPackage couchdaemon provides utilities for processes running as a CouchDB os_daemon.

Package couchdb imports 15 packages (graph) and is imported by 8 packages. Updated 2017-09-18. Refresh now. Tools for package owners.