couchdb

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2020 License: MIT Imports: 15 Imported by: 10

README

What's this?

go-couchdb is yet another CouchDB client written in Go. It was written because all the other ones didn't provide functionality that I need.

The API is not fully baked at this time and may change.

This project contains three Go packages:

package couchdb GoDoc

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

This wraps the CouchDB HTTP API.

package couchapp GoDoc

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

This provides functionality similar to the original couchapp tool, namely compiling a filesystem directory into a JSON object and storing the object as a CouchDB design document.

package couchdaemon GoDoc

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

This package contains some functions that help you write Go programs that run as a daemon started by CouchDB, e.g. fetching values from the CouchDB config.

Tests

You can run the unit tests with go test.

Build Status

Documentation

Overview

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Conflict 

func Conflict(err error) bool

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

func ErrorStatus 

func ErrorStatus(err error, statusCode int) bool

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

func NotFound 

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 

func Unauthorized(err error) bool

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

Types

type Attachment 

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 

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 

func BasicAuth(username, password string) Auth

BasicAuth returns an Auth that performs HTTP Basic Authentication.

func ProxyAuth 

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 

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.
	// This is usually a string, but may also be a number for couchdb 0.x servers.
	//
	// For poll-style feeds (feed modes "normal", "longpoll"), this is set to the
	// last_seq value sent by CouchDB after all feed rows have been read.
	Seq interface{} `json:"seq"`

	// Pending is the count of remaining items in the feed. This is set for poll-style
	// feeds (feed modes "normal", "longpoll") after the last element has been
	// processed.
	Pending int64 `json:"pending"`

	// 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) ChangesRevs 

func (f *ChangesFeed) ChangesRevs() []string

ChangesRevs returns the rev list of the current result row.

func (*ChangesFeed) Close 

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 

func (f *ChangesFeed) Err() error

Err returns the last error that occurred during iteration.

func (*ChangesFeed) Next 

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 

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

Client represents a remote CouchDB server.

func NewClient 

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 

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

AllDBs returns the names of all existing databases.

func (*Client) CreateDB 

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 

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 

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 

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

DeleteDB deletes an existing database.

func (*Client) EnsureDB 

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

EnsureDB ensures that a database with the given name exists.

func (*Client) Ping 

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 

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 

func (c *Client) URL() string

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

type DB 

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

DB represents a remote CouchDB database.

func (*DB) AllDocs 

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 

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 

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 

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 

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

Delete marks a document revision as deleted.

func (*DB) DeleteAttachment 

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

DeleteAttachment removes an attachment.

func (*DB) Get 

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 

func (db *DB) Name() string

Name returns the name of a database.

func (*DB) Put 

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 

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 

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

PutSecurity sets the database security object.

func (*DB) Rev 

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 

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

Security retrieves the security object of a database.

func (*DB) View 

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 

type DBUpdatesFeed struct {
	Event string      `json:"type"`    // "created" | "updated" | "deleted"
	DB    string      `json:"db_name"` // Event database name
	Seq   interface{} `json:"seq"`     // DB update sequence of the event.
	OK    bool        `json:"ok"`      // Event operation status (deprecated)
	// 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 

func (f *DBUpdatesFeed) Close() error

Close terminates the connection of a feed.

func (*DBUpdatesFeed) Err 

func (f *DBUpdatesFeed) Err() error

Err returns the last error that occurred during iteration.

func (*DBUpdatesFeed) Next 

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 

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 

func (e *Error) Error() string

type Members 

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

Members represents member lists in database security objects.

type Options 

type Options map[string]interface{}

Options represents CouchDB query string parameters.

type Security 

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

Security represents database security objects.

Source Files

View all Source files

Directories

Path Synopsis
cmd
couchapp
The couchapp tool deploys a directory as a CouchDB design document.
 The couchapp tool deploys a directory as a CouchDB design document.
couchfeed
The couchfeed tool logs CouchDB feeds.
 The couchfeed tool logs CouchDB feeds.
Package couchapp implements a mapping from files to CouchDB documents.
 Package couchapp implements a mapping from files to CouchDB documents.
Package couchdaemon provides utilities for processes running as a CouchDB os_daemon.
 Package couchdaemon provides utilities for processes running as a CouchDB os_daemon.

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.