# README
Couchbase Go Client
This is the official Couchbase Go SDK. If you are looking for our previous unofficial prototype Go client library, please see: http://www.github.com/couchbase/go-couchbase.
The Go SDK library allows you to connect to a Couchbase cluster from Go. It is written in pure Go, and uses the included gocbcore library to handle communicating to the cluster over the Couchbase binary protocol.
Useful Links
Source
The project source is hosted at http://github.com/couchbase/gocb.
Documentation
You can explore our API reference through godoc at https://godoc.org/github.com/couchbase/gocb.
You can also find documentation for the Go SDK at the Couchbase Developer Portal.
Bug Tracker
Issues are tracked on Couchbase's public issues.couchbase.com. Contact the site admins regarding login or other problems at issues.couchbase.com (officially) or ask around in couchbase/discuss on gitter.im (unofficially).
Installing
To install the latest stable version, run:
go get gopkg.in/couchbase/gocb.v1
To install the latest developer version, run:
go get github.com/couchbase/gocb
License
Copyright 2016 Couchbase Inc.
Licensed under the Apache License, Version 2.0.
See LICENSE for further details.
# Packages
No description provided by the author
# Functions
Connect creates a new Cluster object for a specific cluster.
DefaultAnalyticsIngestOptions creates a new AnalyticsIngestOptions from a set of defaults.
DefaultStdioLogger gets the default standard I/O logger.
ErrorCause returns the underlying error for an enhanced error.
IngestMethodInsert indicates that the Insert function should be used for kv ingest.
IngestMethodReplace indicates that the Replace function should be used for kv ingest.
IngestMethodUpsert indicates that the Upsert function should be used for kv ingest.
IsKeyExistsError indicates whether the passed error is a key-value "Key Already Exists" error.
IsKeyNotFoundError indicates whether the passed error is a key-value "Key Not Found" error.
IsStatusBusyError indicates whether the passed error is a key-value "server is busy, try again later" error.
IsTmpFailError indicates whether the passed error is a key-value "temporary failure, try again later" error.
NewAnalyticsQuery creates a new AnalyticsQuery object from a query string.
NewMutationState creates a new MutationState for tracking mutation state.
NewN1qlQuery creates a new N1qlQuery object from a query string.
NewQueryDelayRetryBehavior provides a QueryDelayRetryBehavior that will retry at most maxRetries number of times and with an initial retry delay of retryDelay (ms) up to a maximum delay of delayLimit.
NewSearchQuery creates a new SearchQuery object from an index name and query.
NewSpatialQuery creates a new SpatialQuery object from a design document and view name.
NewViewQuery creates a new ViewQuery object from a design document and view name.
PassthroughDataConverterFunction is a DataConverterFunction that returns the data that is passed to it.
QueryExponentialDelayFunction provides retry delay durations (ms) following an exponential increment pattern.
QueryLinearDelayFunction provides retry delay durations (ms) following a linear increment pattern.
SetLogger sets a logger to be used by the library.
SetLogRedactionLevel specifies the level with which logs should be redacted.
UUIDIdGeneratorFunction is a IdGeneratorFunction that creates a UUID ID for each document.
VerboseStdioLogger is a more verbose level of DefaultStdioLogger().
Version returns a string representation of the current SDK version.
# Constants
After indicates to update the index asynchronously after querying.
AnsiHightlightStyle specifies to use ANSI tags to highlight search result hits.
Ascending indicates the query results should be sorted from lowest to highest.
Before indicates to update the index before querying it.
CapiService represents a CouchAPI service (typically for views).
CbasService represents an analytics service.
Couchbase indicates a Couchbase bucket type.
DefaultHighlightStyle specifies to use the default to highlight search result hits.
Descending indicates the query results should be sorted from highest to lowest.
DiagStateDisconnected indicates that the connection is disconnected.
DiagStateOk indicates that the connection state is ok.
Ephemeral indicates an Ephemeral bucket type.
ExternalDomain specifies users that are externally stored (in LDAP for instance).
FtsService represents a full-text-search service.
HtmlHighlightStyle specifies to use HTML tags to highlight search result hits.
IndexTypeN1ql indicates that GSI was used to build the index.
IndexTypeView indicates that views were used to build the index.
LocalDomain specifies users that are locally stored in Couchbase.
Various logging levels (or subsystems) which can categorize the message.
Various logging levels (or subsystems) which can categorize the message.
Various logging levels (or subsystems) which can categorize the message.
Various logging levels (or subsystems) which can categorize the message.
Various logging levels (or subsystems) which can categorize the message.
Various logging levels (or subsystems) which can categorize the message.
Various logging levels (or subsystems) which can categorize the message.
Memcached indicates a Memcached bucket type.
MemdService represents a memcached service.
MgmtService represents a management service (typically ns_server).
N1qlService represents a N1QL service (typically for query).
None indicates that no special behaviour should be used.
NotBounded indicates no data consistency is required.
QueryProfileNone disables query profiling.
QueryProfilePhases includes phase profiling information in the query response.
QueryProfileTimings includes timing profiling information in the query response.
RedactFull indicates to fully redact all possible identifying information from logs.
RedactNone indicates to perform no redactions.
RedactPartial indicates to redact all possible user-identifying information from logs.
RequestPlus indicates that request-level data consistency is required.
SearchIndexIngestControlOpPause specifies to use FTS ingest control op of pause.
SearchIndexIngestControlOpResume specifies to use FTS ingest control op of resume.
SearchIndexPlanFreezeControlOpPause specifies to use FTS plan freeze control op of freeze.
SearchIndexPlanFreezeControlOpResume specifies to use FTS plan freeze control op of unfreeze.
SearchIndexQueryControlOpPause specifies to use FTS query control op of allow.
SearchIndexQueryControlOpResume specifies to use FTS ingest control op of disallow.
SearchIndexSourceTypeCouchbase specifies to use a couchbase FTS index sourceType.
SearchIndexSourceTypeMemcached specifies to use a memcached FTS index sourceType.
StatementPlus inidcates that statement-level data consistency is required.
SubdocDocFlagAccessDeleted indicates that you wish to receive soft-deleted documents.
SubdocDocFlagMkDoc indicates that the document should be created if it does not already exist.
SubdocDocFlagNone indicates no special behaviours.
SubdocDocFlagReplaceDoc indices that this operation should be a replace rather than upsert.
SubdocFlagCreatePath indicates you wish to recursively create the tree of paths if it does not already exist within the document.
SubdocFlagNone indicates no special behaviours.
SubdocFlagUseMacros indicates that you wish macro substitution to occur on the value.
SubdocFlagXattr indicates your path refers to an extended attribute rather than the document.
# Variables
ErrAccessError occurs when you do not have access to the specified resource.
ErrAuthError occurs when there is an issue with authentication (bad password?).
ErrBadHosts occurs when an invalid list of hosts is specified for bootstrapping.
ErrBusy occurs when the server is too busy to handle your operation.
ErrCliInternalError indicates an internal error occurred within the client.
ErrDispatchFail occurs when we failed to execute an operation due to internal routing issues.
ErrDurabilityTimeout occurs when the server took too long to meet the specified durability requirements.
ErrFacetNoRanges occurs when a range-based facet is specified but no ranges were indicated.
ErrIndexAlreadyExists occurs when an operation expects an index not to exist, but it was found.
ErrIndexInvalidName occurs when an invalid name was specified for an index.
ErrIndexNoFields occurs when an index with no fields is created.
ErrIndexNotFound occurs when an operation expects an index but it was not found.
ErrInternalError occurs when an internal error has prevented an operation from succeeding.
ErrInvalidCert occurs when the specified certificate is not valid.
ErrInvalidCredentials is returned when an invalid set of credentials is provided for a service.
ErrInvalidReplica occurs when a specified replica index is invalid.
ErrInvalidServer occurs when a specified server index is invalid.
ErrInvalidVBucket occurs when a specified vbucket index is invalid.
ErrKeyExists occurs when the key already exists on the server.
ErrKeyNotFound occurs when the key is not found on the server.
ErrMixedAuthentication occurs when a combination of certification authentication and password authentication are used.
ErrMixedCertAuthentication occurs when client certificate authentication is setup but CertAuthenticator is not used or vise versa.
ErrNetwork occurs when various generic network errors occur.
ErrNoHosts occurs when a cluster manager operation is performed before any buckets are opened and there are no http hosts specified to use.
ErrNonZeroCas occurs when an operation that require a CAS value of 0 is used with a non-zero value.
ErrNoOpenBuckets occurs when a cluster-level operation is performed before any buckets are opened.
ErrNoReplicas occurs when an operation expecting replicas is performed, but no replicas are available.
ErrNoResults occurs when no results are available to a query.
ErrNotEnoughReplicas occurs when not enough replicas exist to match the specified durability requirements.
ErrNotStored occurs when an item fails to be stored.
ErrNotSupported occurs when an operation is performed which is not supported.
ErrOutOfMemory occurs when the server has run out of memory to process requests.
ErrOverload occurs when more operations were dispatched than the client is capable of writing.
ErrProtocol occurs when an invalid protocol is specified for bootstrapping.
ErrRangeError occurs when an invalid range is specified.
ErrRollback occurs when a server rollback has occurred making the operation no longer valid.
ErrSearchIndexAlreadyExists occurs when an invalid source name was specific for a search index.
ErrSearchIndexInvalidIngestControlOp occurs when an invalid ingest control op was specific for a search index.
ErrSearchIndexInvalidName occurs when an invalid name was specified for a search index.
ErrSearchIndexInvalidPlanFreezeControlOp occurs when an invalid plan freeze control op was specific for a search index.
ErrSearchIndexInvalidQueryControlOp occurs when an invalid query control op was specific for a search index.
ErrSearchIndexInvalidSourceName occurs when an invalid source name was specific for a search index.
ErrSearchIndexInvalidSourceType occurs when an invalid source type was specific for a search index.
ErrSearchIndexMissingType occurs when no type was specified for a search index.
ErrShutdown occurs when an operation is performed on a bucket that has been closed.
ErrStreamClosed occurs when an error is related to a stream closing.
ErrStreamDisconnected occurs when a stream is closed due to a connection dropping.
ErrStreamStateChanged occurs when an error is related to a cluster rebalance.
ErrStreamTooSlow occurs when a stream is closed due to being too slow at consuming data.
ErrSubDocBadCombo occurs when a multi-operation sub-document operation is performed and operations within the package of ops conflict with each other.
ErrSubDocBadDelta occurs when a sub-document counter operation is performed and the specified delta is not valid.
ErrSubDocBadMulti occurs when a multi-operation sub-document operation is performed and operations within the package of ops conflict with each other.
ErrSubDocBadRange occurs when a sub-document operation is performed with a bad range.
ErrSubDocCantInsert occurs when a sub-document operation could not insert.
ErrSubDocDocTooDeep occurs when an operation would cause a document to be nested beyond the depth limits allowed by the sub-document specification.
ErrSubDocMultiPathFailureDeleted occurs when a Multi Path Failure occurs on a soft-deleted document.
ErrSubDocNotJson occurs when a sub-document operation is performed on a document which is not JSON.
ErrSubDocPathExists occurs when a sub-document operation expects a path not to exists, but the path was found in the document.
ErrSubDocPathInvalid occurs when a sub-document path could not be parsed.
ErrSubDocPathMismatch occurs when a sub-document operation specifies a path which does not match the document structure (field access on an array).
ErrSubDocPathNotFound occurs when a sub-document operation targets a path which does not exist in the specifie document.
ErrSubDocPathTooBig occurs when a sub-document path is too big.
ErrSubDocSuccessDeleted occurs when a multi-operation sub-document operation is performed on a soft-deleted document.
ErrSubDocValueTooDeep occurs when a sub-document operation specifies a value which is deeper than the depth limits of the sub-document specification.
ErrSubDocXattrCannotModifyVAttr occurs when a mutation is attempted upon a virtual attribute (which are immutable by definition).
ErrSubDocXattrInvalidFlagCombo occurs when an invalid set of extended-attribute flags is passed to a sub-document operation.
ErrSubDocXattrInvalidKeyCombo occurs when an invalid set of key operations are specified for a extended-attribute sub-document operation.
ErrSubDocXattrUnknownMacro occurs when an invalid macro value is specified.
ErrSubDocXattrUnknownVAttr occurs when an invalid virtual attribute is specified.
ErrTimeout occurs when an operation times out.
ErrTmpFail occurs when the server is not immediately able to handle your request.
ErrTooBig occurs when the document is too big to be stored.
# Structs
AnalyticsIngestOptions contains the options for an Analytics query to KV ingest.
AnalyticsQuery represents a pending Analytics query.
AnalyticsResultMetrics encapsulates various metrics gathered during a queries execution.
AnalyticsWarning represents any warning generating during the execution of an Analytics query.
AppendOp represents a type of `BulkOp` used for Append operations.
AuthCredsRequest encapsulates the data for a credential request from the new Authenticator interface.
Bucket is an interface representing a single bucket within a cluster.
BucketAuthenticator provides a password for a single bucket.
BucketInternal holds various internally used bucket extension methods.
BucketManager provides methods for performing bucket management operations.
BucketSettings holds information about the settings for a bucket.
CertAuthenticator implements an Authenticator which can be used with certificate authentication.
CertificateAuthenticator is included for backwards compatibility only.
Cluster represents a connection to a specific Couchbase cluster.
ClusterAuthenticator implements an Authenticator which uses a list of buckets and passwords.
ClusterManager provides methods for performing cluster management operations.
ClusterManagerInternal holds internally used cluster manager extension methods.
CounterOp represents a type of `BulkOp` used for Counter operations.
DefaultTranscoder implements the default transcoding behaviour of all Couchbase SDKs.
DesignDocument represents a Couchbase design document containing multiple views.
DiagnosticEntry represents a single entry in a diagnostics report.
DiagnosticReport encapsulates the results of a Diagnostics operation.
DocumentFragment represents multiple chunks of a full Document.
GetAndTouchOp represents a type of `BulkOp` used for GetAndTouch operations.
GetOp represents a type of `BulkOp` used for Get operations.
IndexInfo represents a Couchbase GSI index.
InsertOp represents a type of `BulkOp` used for Insert operations.
LookupInBuilder is a builder used to create a set of sub-document lookup operations.
MultiError encapsulates multiple errors that may be returned by one method.
MutateInBuilder is a builder used to create a set of sub-document mutation operations.
MutationState holds and aggregates MutationToken's across multiple operations.
MutationToken holds the mutation state information from an operation.
N1qlQuery represents a pending N1QL query.
NodeMetadata contains information about a node in the cluster.
PasswordAuthenticator implements an Authenticator which uses an RBAC username and password.
PingReport encapsulates the details from a executed ping operation.
PingServiceEntry represents a single entry in a ping report.
PrependOp represents a type of `BulkOp` used for Prepend operations.
QueryDelayRetryBehavior provides the behavior to use when retrying queries with a backoff delay.
QueryResultMetrics encapsulates various metrics gathered during a queries execution.
RemoveOp represents a type of `BulkOp` used for Remove operations.
ReplaceOp represents a type of `BulkOp` used for Replace operations.
SearchIndexDefinitionBuilder provides methods for building a Couchbase FTS index.
SearchIndexManager provides methods for performing Couchbase FTS index management.
SearchQuery represents a pending search query.
SearchResultDateFacet holds the results of a date facet in search results.
SearchResultFacet holds the results of a specified facet in search results.
SearchResultHit holds a single hit in a list of search results.
SearchResultLocation holds the location of a hit in a list of search results.
SearchResultNumericFacet holds the results of a numeric facet in search results.
SearchResultStatus holds the status information for an executed search query.
SearchResultTermFacet holds the results of a term facet in search results.
SpatialQuery represents a pending spatial query.
StreamingBucket represents a bucket connection used for streaming data over DCP.
ThresholdLoggingTracer is a specialized Tracer implementation which will automatically log operations which fall outside of a set of thresholds.
TouchOp represents a type of `BulkOp` used for Touch operations.
UpsertOp represents a type of `BulkOp` used for Upsert operations.
User represents a user which was retrieved from the server.
UserRole represents a role for a particular user on the server.
UserSettings represents a user during user creation.
View represents a Couchbase view within a design document.
ViewQuery represents a pending view query.
# Interfaces
AnalyticsDeferredResultHandle allows access to the handle of a deferred Analytics query.
AnalyticsResults allows access to the results of a Analytics query.
Authenticator provides an interface to authenticate to each service.
BulkOp represents a single operation that can be submitted (within a list of more operations) to .Do() You can create a bulk operation by instantiating one of the implementations of BulkOp, such as GetOp, UpsertOp, ReplaceOp, and more.
Logger defines a logging interface.
QueryResults allows access to the results of a N1QL query.
QueryRetryBehavior defines the behavior to be used when retrying queries.
SearchResults allows access to the results of a search query.
Transcoder provides an interface for transforming Go values to and from raw bytes for storage and retreival from Couchbase data storage.
ViewResultMetrics allows access to the TotalRows value from the view response.
ViewResults implements an iterator interface which can be used to iterate over the rows of the query results.
# Type aliases
AuthDomain specifies the user domain of a specific user.
BucketAuthenticatorMap is a map of bucket name to BucketAuthenticator.
BucketType specifies the kind of bucket.
Cas represents the specific state of a document on the cluster.
ConsistencyMode indicates the level of data consistency desired for a query.
DataConverterFunction is called to convert from analytics document format to kv document.
DiagConnState represents the state of a connection in a diagnostics report.
IdGeneratorFunction is called to create an ID for a document.
IndexType provides information on the type of indexer used for an index.
LogLevel specifies the severity of a log message.
LogRedactLevel specifies the degree with which to redact the logs.
QueryProfileType specifies the profiling mode to use during a query.
QueryRetryDelayFunction is called to get the next try delay.
SearchHighlightStyle indicates the type of highlighting to use for a search query.
ServerStats is a tree of statistics information returned from the server.
ServiceType specifies a particular Couchbase service type.
SortOrder specifies the ordering for the view queries results.
StaleMode specifies the consistency required for a view query.
SubdocDocFlag specifies document-level flags for a sub-document operation.
SubdocFlag provides special handling flags for sub-document operations.
UserPassPair represents a username and password pair.