couchbase

package module
v0.0.0-...-a230b9d Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2013 License: MIT Imports: 20 Imported by: 0

README

A smart client for couchbase in go

This is an evolving package, but does provide a useful interface to a couchbase server including all of the pool/bucket discovery features, compatible key distribution with other clients, and vbucket motion awareness so application can continue to operate during rebalances.

It also supports view querying with source node randomization so you don't bang on all one node to do all the work.

Install

go get github.com/couchbaselabs/go-couchbase

Example

c, err := couchbase.Connect("http://dev-couchbase.example.com:8091/")
if err != nil {
	log.Fatalf("Error connecting:  %v", err)
}

pool, err := c.GetPool("default")
if err != nil {
	log.Fatalf("Error getting pool:  %v", err)
}

bucket, err := pool.GetBucket("default")
if err != nil {
	log.Fatalf("Error getting bucket:  %v", err)
}

bucket.Set("someKey", []string{"an", "example", "list"})

Documentation

Overview

A smart client for go.

Usage: 

client, err := couchbase.Connect("http://myserver:8091/")
handleError(err)
pool, err := client.GetPool("default")
handleError(err)
bucket, err := pool.GetBucket("MyAwesomeBucket")
handleError(err)
...

or a shortcut for the bucket directly 

bucket, err := couchbase.GetBucket("http://myserver:8091/", "default", "default")

in any case, you can specify authentication credentials using standard URL userinfo syntax: 

b, err := couchbase.GetBucket("http://bucketname:bucketpass@myserver:8091/",
        "default", "bucket")

Index

Constants

View Source 
const (
	// If set, value is raw []byte or nil; don't JSON-encode it.
	Raw = WriteOptions(1 << iota)
	// If set, Write fails with ErrKeyExists if key already has a value.
	AddOnly
	// If set, Write will wait until the value is written to disk.
	Persist
	// If set, Write will wait until the value is available to be indexed by views.
	// (In Couchbase Server 2.x, this has the same effect as the Persist flag.)
	Indexable
)
View Source 
const UpdateCancel = memcached.CASQuit

Return this as the error from an UpdateFunc to cancel the Update operation.

Variables

View Source 
var ConnPoolTimeout = time.Hour * 24 * 30
View Source 
var ErrKeyExists = errors.New("Key exists")

Error returned from Write with AddOnly flag, when key already exists in the bucket.

View Source 
var ErrOverwritten = errors.New("Overwritten")

Returned from WaitForPersistence (or Write, if the Persistent or Indexable flag is used) if the value has been overwritten by another before being persisted.

View Source 
var ErrTimeout = errors.New("Timeout")

Returned from WaitForPersistence (or Write, if the Persistent or Indexable flag is used) if the value hasn't been persisted by the timeout interval

View Source 
var HttpClient = http.DefaultClient

The HTTP Client To Use

View Source 
var MaxBulkRetries = 10

Maximum number of times to retry a chunk of a bulk get on error.

View Source 
var TimeoutError = errors.New("timeout waiting to build connection")

Functions

func CleanupHost 

func CleanupHost(h, commonSuffix string) string

Return the hostname with the given suffix removed.

func FindCommonSuffix 

func FindCommonSuffix(input []string) string

Find the longest common suffix from the given strings.

Types

type AuthHandler 

type AuthHandler interface {
	GetCredentials() (string, string)
}

Auth callback gets the auth username and password for the given bucket.

type Bucket 

type Bucket struct {
	AuthType            string             `json:"authType"`
	Capabilities        []string           `json:"bucketCapabilities"`
	CapabilitiesVersion string             `json:"bucketCapabilitiesVer"`
	Type                string             `json:"bucketType"`
	Name                string             `json:"name"`
	NodeLocator         string             `json:"nodeLocator"`
	Nodes               []Node             `json:"nodes"`
	Quota               map[string]float64 `json:"quota,omitempty"`
	Replicas            int                `json:"replicaNumber"`
	Password            string             `json:"saslPassword"`
	URI                 string             `json:"uri"`
	StreamingURI        string             `json:"streamingUri"`
	LocalRandomKeyURI   string             `json:"localRandomKeyUri,omitempty"`
	UUID                string             `json:"uuid"`
	DDocs               struct {
		URI string `json:"uri"`
	} `json:"ddocs,omitempty"`
	VBucketServerMap struct {
		HashAlgorithm string   `json:"hashAlgorithm"`
		NumReplicas   int      `json:"numReplicas"`
		ServerList    []string `json:"serverList"`
		VBucketMap    [][]int  `json:"vBucketMap"`
	} `json:"vBucketServerMap"`
	BasicStats  map[string]interface{} `json:"basicStats,omitempty"`
	Controllers map[string]interface{} `json:"controllers,omitempty"`
	// contains filtered or unexported fields
}

An individual bucket. Herein lives the most useful stuff.

func GetBucket 

func GetBucket(endpoint, poolname, bucketname string) (*Bucket, error)

Convenience function for getting a named bucket from a URL

func (*Bucket) Add 

func (b *Bucket) Add(k string, exp int, v interface{}) (added bool, err error)

Adds a value to this bucket; like Set except that nothing happens if the key exists. The value will be serialized into a JSON document.

func (*Bucket) AddRaw 

func (b *Bucket) AddRaw(k string, exp int, v []byte) (added bool, err error)

Adds a value to this bucket; like SetRaw except that nothing happens if the key exists. The value will be stored as raw bytes.

func (*Bucket) Close 

func (b *Bucket) Close()

Mark this bucket as no longer needed, closing connections it may have open.

func (Bucket) CommonAddressSuffix 

func (b Bucket) CommonAddressSuffix() string

Get the longest common suffix of all host:port strings in the node list.

func (*Bucket) Delete 

func (b *Bucket) Delete(k string) error

Delete a key from this bucket.

func (*Bucket) DeleteDDoc 

func (b *Bucket) DeleteDDoc(docname string) error

Delete a design document.

func (*Bucket) Do 

func (b *Bucket) Do(k string, f func(mc *memcached.Client, vb uint16) error) error

Execute a function on a memcached connection to the node owning key "k"

Note that this automatically handles transient errors by replaying your function on a "not-my-vbucket" error, so don't assume your command will only be executed only once.

func (*Bucket) Get 

func (b *Bucket) Get(k string, rv interface{}) error

Get a value from this bucket. The value is expected to be a JSON stream and will be deserialized into rv.

func (*Bucket) GetBulk 

func (b *Bucket) GetBulk(keys []string) (map[string]*gomemcached.MCResponse, error)

func (*Bucket) GetDDoc 

func (b *Bucket) GetDDoc(docname string, into interface{}) error

Get a design doc.

func (*Bucket) GetDDocs 

func (b *Bucket) GetDDocs() (DDocsResult, error)

Get the design documents

func (*Bucket) GetPool 

func (b *Bucket) GetPool() *Pool

Get the pool to which this bucket belongs.

func (*Bucket) GetRaw 

func (b *Bucket) GetRaw(k string) ([]byte, error)

Get a raw value from this bucket.

func (*Bucket) GetStats 

func (b *Bucket) GetStats(which string) map[string]map[string]string

Get a set of stats from all servers.

Returns a map of server ID -> map of stat key to map value.

func (*Bucket) Gets 

func (b *Bucket) Gets(k string, rv interface{}, caso *uint64) error

Get a value from this bucket, including its CAS counter. The value is expected to be a JSON stream and will be deserialized into rv.

func (*Bucket) GetsRaw 

func (b *Bucket) GetsRaw(k string) (data []byte, flags int,
	cas uint64, err error)

Get a raw value from this bucket, including its CAS counter and flags.

func (*Bucket) Incr 

func (b *Bucket) Incr(k string, amt, def uint64, exp int) (uint64, error)

Increment a key

func (Bucket) NodeAddresses 

func (b Bucket) NodeAddresses() []string

Get the (sorted) list of memcached node addresses (hostname:port).

func (*Bucket) Observe 

func (b *Bucket) Observe(k string) (result memcached.ObserveResult, err error)

Observes the current state of a document.

func (*Bucket) PutDDoc 

func (b *Bucket) PutDDoc(docname string, value interface{}) error

Install a design document.

func (*Bucket) Set 

func (b *Bucket) Set(k string, exp int, v interface{}) error

Set a value in this bucket. The value will be serialized into a JSON document.

func (*Bucket) SetRaw 

func (b *Bucket) SetRaw(k string, exp int, v []byte) error

Set a value in this bucket. The value will be stored as raw bytes.

func (*Bucket) StartTapFeed 

func (b *Bucket) StartTapFeed(args *memcached.TapArguments) (*TapFeed, error)

Creates and starts a new Tap feed

func (*Bucket) Update 

func (b *Bucket) Update(k string, exp int, callback UpdateFunc) error

Safe update of a document, avoiding conflicts by using CAS.

The callback function will be invoked with the current raw document contents (or nil if the document doesn't exist); it should return the updated raw contents (or nil to delete.) If it decides not to change anything it can return UpdateCancel as the error.

If another writer modifies the document between the get and the set, the callback will be invoked again with the newer value.

func (*Bucket) VBHash 

func (b *Bucket) VBHash(key string) uint32

Get the vbucket for the given key.

func (*Bucket) View 

func (b *Bucket) View(ddoc, name string, params map[string]interface{}) (ViewResult, error)

Execute a view.

The ddoc parameter is just the bare name of your design doc without the "_design/" prefix.

Parameters are string keys with values that correspond to couchbase view parameters. Primitive should work fairly naturally (booleans, ints, strings, etc...) and other values will attempt to be JSON marshaled (useful for array indexing on on view keys, for example).

Example: 

res, err := couchbase.View("myddoc", "myview", map[string]interface{}{
    "group_level": 2,
    "start_key":    []interface{}{"thing"},
    "end_key":      []interface{}{"thing", map[string]string{}},
    "stale": false,
    })

func (*Bucket) ViewCustom 

func (b *Bucket) ViewCustom(ddoc, name string, params map[string]interface{},
	vres interface{}) error

Perform a view request that can map row values to a custom type.

See the source to View for an example usage.

func (*Bucket) ViewURL 

func (b *Bucket) ViewURL(ddoc, name string,
	params map[string]interface{}) (string, error)

Build a URL for a view with the given ddoc, view name, and parameters.

func (*Bucket) WaitForPersistence 

func (b *Bucket) WaitForPersistence(k string, cas uint64, deletion bool) error

WaitForPersistence waits for an item to be considered durable.

Besides transport errors, ErrOverwritten may be returned if the item is overwritten before it reaches durability. ErrTimeout may occur if the item isn't found durable in a reasonable amount of time.

func (*Bucket) Write 

func (b *Bucket) Write(k string, flags, exp int, v interface{},
	opt WriteOptions) (err error)

General-purpose value setter.

The Set, Add and Delete methods are just wrappers around this. The interpretation of `v` depends on whether the `Raw` option is given. If it is, v must be a byte array or nil. (A nil value causes a delete.) If `Raw` is not given, `v` will be marshaled as JSON before being written. It must be JSON-marshalable and it must not be nil.

func (*Bucket) WriteUpdate 

func (b *Bucket) WriteUpdate(k string, exp int, callback WriteUpdateFunc) error

Safe update of a document, avoiding conflicts by using CAS. WriteUpdate is like Update, except that the callback can return a set of WriteOptions, of which Persist and Indexable are recognized: these cause the call to wait until the document update has been persisted to disk and/or become available to index.

type Client 

type Client struct {
	BaseURL *url.URL

	Info     Pools
	Statuses [256]uint64
	// contains filtered or unexported fields
}

The couchbase client gives access to all the things.

func Connect 

func Connect(baseU string) (Client, error)

Connect to a couchbase cluster. An authentication handler will be created from the userinfo in the URL if provided.

func ConnectWithAuth 

func ConnectWithAuth(baseU string, ah AuthHandler) (c Client, err error)

ConnectWithAuth connects to a couchbase cluster with the given authentication handler.

func (*Client) GetPool 

func (c *Client) GetPool(name string) (p Pool, err error)

Get a pool from within the couchbase cluster (usually "default").

type DDoc 

type DDoc struct {
	Meta map[string]interface{} `json:"meta"`
	Json DDocJSON               `json:"json"`
}

type DDocJSON 

type DDocJSON struct {
	Language string                    `json:"language,omitempty"`
	Views    map[string]ViewDefinition `json:"views"`
}

type DDocRow 

type DDocRow struct {
	DDoc DDoc `json:"doc"`
}

type DDocsResult 

type DDocsResult struct {
	Rows []DDocRow `json:"rows"`
}

type DocId 

type DocId string

Document ID type for the startkey_docid parameter in views.

type Node 

type Node struct {
	ClusterCompatibility int                `json:"clusterCompatibility"`
	ClusterMembership    string             `json:"clusterMembership"`
	CouchAPIBase         string             `json:"couchApiBase"`
	Hostname             string             `json:"hostname"`
	InterestingStats     map[string]float64 `json:"interestingStats,omitempty"`
	MCDMemoryAllocated   float64            `json:"mcdMemoryAllocated"`
	MCDMemoryReserved    float64            `json:"mcdMemoryReserved"`
	MemoryFree           float64            `json:"memoryFree"`
	MemoryTotal          float64            `json:"memoryTotal"`
	OS                   string             `json:"os"`
	Ports                map[string]int     `json:"ports"`
	Status               string             `json:"status"`
	Uptime               int                `json:"uptime,string"`
	Version              string             `json:"version"`
	ThisNode             bool               `json:"thisNode,omitempty"`
}

A computer in a cluster running the couchbase software.

type Pool 

type Pool struct {
	BucketMap map[string]Bucket
	Nodes     []Node

	BucketURL map[string]string `json:"buckets"`
	// contains filtered or unexported fields
}

A pool of nodes and buckets.

func (*Pool) GetBucket 

func (p *Pool) GetBucket(name string) (*Bucket, error)

Get a bucket from within this pool.

func (*Pool) GetClient 

func (p *Pool) GetClient() *Client

Get the client from which we got this pool.

type Pools 

type Pools struct {
	ComponentsVersion     map[string]string `json:"componentsVersion,omitempty"`
	ImplementationVersion string            `json:"implementationVersion"`
	IsAdmin               bool              `json:"isAdminCreds"`
	UUID                  string            `json:"uuid"`
	Pools                 []RestPool        `json:"pools"`
}

type RestPool 

type RestPool struct {
	Name         string `json:"name"`
	StreamingURI string `json:"streamingUri"`
	URI          string `json:"uri"`
}

type TapFeed 

type TapFeed struct {
	C <-chan memcached.TapEvent
	// contains filtered or unexported fields
}

A Tap feed. Events from the bucket can be read from the channel 'C'. Remember to call Close() on it when you're done, unless its channel has closed itself already.

func (*TapFeed) Close 

func (feed *TapFeed) Close() error

Closes a Tap feed.

type UpdateFunc 

type UpdateFunc func(current []byte) (updated []byte, err error)

A callback function to update a document

type ViewDefinition 

type ViewDefinition struct {
	Map    string `json:"map"`
	Reduce string `json:"reduce,omitempty"`
}

type ViewError 

type ViewError struct {
	From   string
	Reason string
}

func (ViewError) Error 

func (ve ViewError) Error() string

type ViewResult 

type ViewResult struct {
	TotalRows int `json:"total_rows"`
	Rows      []ViewRow
	Errors    []ViewError
}

type ViewRow 

type ViewRow struct {
	ID    string
	Key   interface{}
	Value interface{}
	Doc   *interface{}
}

type WriteOptions 

type WriteOptions int

A set of option flags for the Write method.

type WriteUpdateFunc 

type WriteUpdateFunc func(current []byte) (updated []byte, opt WriteOptions, err error)

A callback function to update a document

Source Files

View all Source files

Directories

Path Synopsis
examples
basic
hello
hello_observe
hello_tap
tools
loadfile
view2go
Utilities for working with Couchbase
 Utilities for working with Couchbase

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.