driver

Documentation

Overview

Package driver defines interfaces to be implemented by database drivers as used by package kivik.

Most code should use package kivik.

Index

• type AttachmentMetaer
• type Authenticator
• type Bookmarker
• type BulkDocer
• type BulkResult
• type BulkResults
• type Change
• type ChangedRevs
  • func (c *ChangedRevs) UnmarshalJSON(data []byte) error
• type Changes
• type Client
• type ClientReplicator
• type Copier
• type DB
• type DBFlusher
• type DBOpts
• type DBStats
• type DBUpdate
• type DBUpdater
• type DBUpdates
• type Driver
• type Explainer
• type Finder
• type Index
• type MD5sum
• type Members
• type OldAttachmentMetaer
• type OldBulkDocer
• type QueryPlan
• type Replication
• type ReplicationInfo
• type Rever
• type Row
• type Rows
• type RowsWarner
• type Security
• type SequenceID
  • func (id *SequenceID) UnmarshalJSON(data []byte) error
• type Session
• type Sessioner
• type Version

Types

type AttachmentMetaer

type AttachmentMetaer interface {
	// GetAttachmentMetaOpts returns meta information about an attachment.
	GetAttachmentMeta(ctx context.Context, docID, rev, filename string, options map[string]interface{}) (contentType string, md5sum MD5sum, err error)
}

AttachmentMetaer is an optional interface which may be satisfied by a DB. If satisfied, it may be used to fetch meta data about an attachment. If not satisfied, GetAttachment will be used instead.

type Authenticator

type Authenticator interface {
	// Authenticate attempts to authenticate the client using an authenticator.
	// If the authenticator is not known to the client, an error should be
	// returned.
	Authenticate(ctx context.Context, authenticator interface{}) error
}

Authenticator is an optional interface that may be implemented by a Client that supports authenitcated connections.

type Bookmarker

type Bookmarker interface {
	// Bookmark returns an opaque bookmark string used for paging, added to
	// the /_find endpoint in CouchDB 2.1.1.  See the CouchDB documentation for
	// usage: http://docs.couchdb.org/en/2.1.1/api/database/find.html#pagination
	Bookmark() string
}

Bookmarker is an optional interface for returning a paging bookmark.

type BulkDocer

type BulkDocer interface {
	// BulkDocs alls bulk create, update and/or delete operations. It returns an
	// iterator over the results.
	BulkDocs(ctx context.Context, docs []interface{}, options map[string]interface{}) (BulkResults, error)
}

BulkDocer is an optional interface which may be implemented by a driver to support bulk insert/update operations. For any driver that does not support the BulkDocer interface, the Put or CreateDoc methods will be called for each document to emulate the same functionality.

type BulkResult

type BulkResult struct {
	ID    string `json:"id"`
	Rev   string `json:"rev"`
	Error error
}

BulkResult is the result of a single doc update in a BulkDocs request.

type BulkResults

type BulkResults interface {
	// Next is called to populate *BulkResult with the values of the next bulk
	// result in the set.
	//
	// Next should return io.EOF when there are no more results.
	Next(*BulkResult) error
	// Close closes the bulk results iterator.
	Close() error
}

BulkResults is an iterator over the results for a BulkDocs call.

type Change

type Change struct {
	// ID is the document ID to which the change relates.
	ID string `json:"id"`
	// Seq is the update sequence for the changes feed.
	Seq SequenceID `json:"seq"`
	// Deleted is set to true for the changes feed, if the document has been
	// deleted.
	Deleted bool `json:"deleted"`
	// Changes represents a list of document leaf revisions for the /_changes
	// endpoint.
	Changes ChangedRevs `json:"changes"`
	// Doc is the raw, un-decoded JSON document. This is only populated when
	// include_docs=true is set.
	Doc json.RawMessage `json:"doc"`
}

Change represents the changes to a single document.

type ChangedRevs

type ChangedRevs []string

ChangedRevs represents a "changes" field of a result in the /_changes stream.

func (*ChangedRevs) UnmarshalJSON

func (c *ChangedRevs) UnmarshalJSON(data []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface

type Changes

type Changes interface {
	// Next is called to populate *Change with the values of the next value in
	// the changes feed.
	//
	// Next should return io.EOF when the changes feed is closed by request.
	Next(*Change) error
	// Close closes the rows iterator.
	Close() error
}

Changes is an iterator of the database changes feed.

type Client

type Client interface {
	// Version returns the server implementation's details.
	Version(ctx context.Context) (*Version, error)
	// AllDBs returns a list of all existing database names.
	AllDBs(ctx context.Context, options map[string]interface{}) ([]string, error)
	// DBExists returns true if the database exists.
	DBExists(ctx context.Context, dbName string, options map[string]interface{}) (bool, error)
	// CreateDB creates the requested DB. The dbName is validated as a valid
	// CouchDB database name prior to calling this function, so the driver can
	// assume a valid name.
	CreateDB(ctx context.Context, dbName string, options map[string]interface{}) error
	// DestroyDB deletes the requested DB.
	DestroyDB(ctx context.Context, dbName string, options map[string]interface{}) error
	// DB returns a handleto the requested database
	DB(ctx context.Context, dbName string, options map[string]interface{}) (DB, error)
}

Client is a connection to a database server.

type ClientReplicator

type ClientReplicator interface {
	// Replicate initiates a replication.
	Replicate(ctx context.Context, targetDSN, sourceDSN string, options map[string]interface{}) (Replication, error)
	// GetReplications returns a list of replicatoins (i.e. all docs in the
	// _replicator database)
	GetReplications(ctx context.Context, options map[string]interface{}) ([]Replication, error)
}

ClientReplicator is an optional interface that may be implemented by a Client that supports replication between two database.

type Copier

type Copier interface {
	Copy(ctx context.Context, targetID, sourceID string, options map[string]interface{}) (targetRev string, err error)
}

Copier is an optional interface that may be implemented by a DB.

If a DB does implement Copier, Copy() functions will use it. If a DB does not implement the Copier interface, or if a call to Copy() returns an http.StatusUnimplemented, the driver will emulate a copy by doing a GET followed by PUT.

type DB

type DB interface {
	// AllDocs returns all of the documents in the database, subject to the
	// options provided.
	AllDocs(ctx context.Context, options map[string]interface{}) (Rows, error)
	// Get fetches the requested document from the database, and unmarshals it
	// into doc.
	Get(ctx context.Context, docID string, options map[string]interface{}) (json.RawMessage, error)
	// CreateDoc creates a new doc, with a server-generated ID.
	CreateDoc(ctx context.Context, doc interface{}) (docID, rev string, err error)
	// Put writes the document in the database.
	Put(ctx context.Context, docID string, doc interface{}) (rev string, err error)
	// Delete marks the specified document as deleted.
	Delete(ctx context.Context, docID, rev string) (newRev string, err error)
	// Stats returns database statistics.
	Stats(ctx context.Context) (*DBStats, error)
	// Compact initiates compaction of the database.
	Compact(ctx context.Context) error
	// CompactView initiates compaction of the view.
	CompactView(ctx context.Context, ddocID string) error
	// ViewCleanup cleans up stale view files.
	ViewCleanup(ctx context.Context) error
	// Security returns the database's security document.
	Security(ctx context.Context) (*Security, error)
	// SetSecurity sets the database's security document.
	SetSecurity(ctx context.Context, security *Security) error
	// Changes returns a Rows iterator for the changes feed. In continuous mode,
	// the iterator will continue indefinitely, until Close is called.
	Changes(ctx context.Context, options map[string]interface{}) (Changes, error)
	// PutAttachment uploads an attachment to the specified document, returning
	// the new revision.
	PutAttachment(ctx context.Context, docID, rev, filename, contentType string, body io.Reader) (newRev string, err error)
	// GetAttachment fetches an attachment for the associated document ID. rev
	// may be an empty string to fetch the most recent document version.
	GetAttachment(ctx context.Context, docID, rev, filename string) (contentType string, md5sum MD5sum, body io.ReadCloser, err error)
	// DeleteAttachment deletes an attachment from a document, returning the
	// document's new revision.
	DeleteAttachment(ctx context.Context, docID, rev, filename string) (newRev string, err error)
	// Query performs a query against a view, subject to the options provided.
	// ddoc will be the design doc name without the '_design/' previx.
	// view will be the view name without the '_view/' prefix.
	Query(ctx context.Context, ddoc, view string, options map[string]interface{}) (Rows, error)
}

DB is a database handle.

type DBFlusher

type DBFlusher interface {
	// Flush requests a flush of disk cache to disk or other permanent storage.
	//
	// See http://docs.couchdb.org/en/2.0.0/api/database/compact.html#db-ensure-full-commit
	Flush(ctx context.Context) error
}

DBFlusher is an optional interface that may be implemented by a database that can force a flush of the database backend file(s) to disk or other permanent storage.

type DBOpts

type DBOpts interface {
	CreateDocOpts(ctx context.Context, doc interface{}, options map[string]interface{}) (docID, rev string, err error)
	// PutOpts writes the document in the database.
	PutOpts(ctx context.Context, docID string, doc interface{}, options map[string]interface{}) (rev string, err error)
	// DeleteOpts marks the specified document as deleted.
	DeleteOpts(ctx context.Context, docID, rev string, options map[string]interface{}) (newRev string, err error)
	// StatsOpts returns database statistics.
	PutAttachmentOpts(ctx context.Context, docID, rev, filename, contentType string, body io.Reader, options map[string]interface{}) (newRev string, err error)
	// GetAttachmentOpts fetches an attachment for the associated document ID. rev
	// may be an empty string to fetch the most recent document version.
	GetAttachmentOpts(ctx context.Context, docID, rev, filename string, options map[string]interface{}) (contentType string, md5sum MD5sum, body io.ReadCloser, err error)
	// DeleteAttachmentOpts deletes an attachment from a document, returning the
	// document's new revision.
	DeleteAttachmentOpts(ctx context.Context, docID, rev, filename string, options map[string]interface{}) (newRev string, err error)
}

DBOpts will be merged with DB in Kivik 2.0. It wraps functions that take additional options arguments.

type DBStats

type DBStats struct {
	Name           string `json:"db_name"`
	CompactRunning bool   `json:"compact_running"`
	DocCount       int64  `json:"doc_count"`
	DeletedCount   int64  `json:"doc_del_count"`
	UpdateSeq      string `json:"update_seq"`
	DiskSize       int64  `json:"disk_size"`
	ActiveSize     int64  `json:"data_size"`
	ExternalSize   int64  `json:"-"`
}

DBStats contains database statistics..

type DBUpdate

type DBUpdate struct {
	DBName string `json:"db_name"`
	Type   string `json:"type"`
	Seq    string `json:"seq"`
}

DBUpdate represents a database update event.

type DBUpdater

type DBUpdater interface {
	// DBUpdates must return a channel on which *DBUpdate events are sent,
	// and a function to close the connection.
	DBUpdates() (DBUpdates, error)
}

DBUpdater is an optional interface that may be implemented by a client to provide access to the DB Updates feed.

type DBUpdates

type DBUpdates interface {
	// Next is called to populate DBUpdate with the values of the next update in
	// the feed.
	//
	// Next should return io.EOF when the feed is closed normally.
	Next(*DBUpdate) error
	// Close closes the iterator.
	Close() error
}

DBUpdates is a DBUpdates iterator.

type Driver

type Driver interface {
	// NewClient returns a connection handle to the database. The name is in a
	// driver-specific format.
	NewClient(ctx context.Context, name string) (Client, error)
}

Driver is the interface that must be implemented by a database driver.

type Explainer

type Explainer interface {
	Explain(ctx context.Context, query interface{}) (*QueryPlan, error)
}

The Explainer is an optional interface which provides access to the query explanation API supported by CouchDB 2.0 and newer, and PouchDB 6.3.4 and newer.

type Finder

type Finder interface {
	// Find executes a query using the new /_find interface. If query is a
	// string, []byte, or json.RawMessage, it should be treated as a raw JSON
	// payload. Any other type should be marshaled to JSON.
	Find(ctx context.Context, query interface{}) (Rows, error)
	// CreateIndex creates an index if it doesn't already exist. If the index
	// already exists, it should do nothing. ddoc and name may be empty, in
	// which case they should be provided by the backend. If index is a string,
	// []byte, or json.RawMessage, it should be treated as a raw JSON payload.
	// Any other type should be marshaled to JSON.
	CreateIndex(ctx context.Context, ddoc, name string, index interface{}) error
	// GetIndexes returns a list of all indexes in the database.
	GetIndexes(ctx context.Context) ([]Index, error)
	// Delete deletes the requested index.
	DeleteIndex(ctx context.Context, ddoc, name string) error
}

The Finder is an optional interface which may be implemented by a database. The Finder interface provides access to the new (in CouchDB 2.0) MongoDB-style query interface.

type Index

type Index struct {
	DesignDoc  string      `json:"ddoc,omitempty"`
	Name       string      `json:"name"`
	Type       string      `json:"type"`
	Definition interface{} `json:"def"`
}

Index is a MonboDB-style index definition.

type MD5sum

type MD5sum [16]byte

MD5sum is a 128-bit MD5 checksum.

type Members

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

Members represents the members of a database security document.

type OldAttachmentMetaer

type OldAttachmentMetaer interface {
	// GetAttachmentMeta returns meta information about an attachment.
	GetAttachmentMeta(ctx context.Context, docID, rev, filename string) (contentType string, md5sum MD5sum, err error)
}

OldAttachmentMetaer is deprected. Use AttachmentMetaer instead.

type OldBulkDocer

type OldBulkDocer interface {
	// BulkDocs alls bulk create, update and/or delete operations. It returns an
	// iterator over the results.
	BulkDocs(ctx context.Context, docs []interface{}) (BulkResults, error)
}

OldBulkDocer is deprecated and will be removed in Kivik 2.0. Use BulkDocer instead.

type QueryPlan

type QueryPlan struct {
	DBName   string                 `json:"dbname"`
	Index    map[string]interface{} `json:"index"`
	Selector map[string]interface{} `json:"selector"`
	Options  map[string]interface{} `json:"opts"`
	Limit    int64                  `json:"limit"`
	Skip     int64                  `json:"skip"`

	// Fields is the list of fields to be returned in the result set, or
	// an empty list if all fields are to be returned.
	Fields []interface{}          `json:"fields"`
	Range  map[string]interface{} `json:"range"`
}

QueryPlan is the response of an Explain query.

type Replication

type Replication interface {
	// The following methods are called just once, when the Replication is first
	// returned from Replicate() or GetReplications().
	ReplicationID() string
	Source() string
	Target() string
	StartTime() time.Time
	EndTime() time.Time
	State() string
	Err() error

	// Delete deletes a replication, which cancels it if it is running.
	Delete(context.Context) error
	// Update fetches the latest replication state from the server.
	Update(context.Context, *ReplicationInfo) error
}

Replication represents a _replicator document.

type ReplicationInfo

type ReplicationInfo struct {
	DocWriteFailures int64
	DocsRead         int64
	DocsWritten      int64
	Progress         float64
}

ReplicationInfo represents a snap-shot state of a replication, as provided by the _active_tasks endpoint.

type Rever

type Rever interface {
	// Rev returns the most current revision of the requested document.
	Rev(ctx context.Context, docID string) (rev string, err error)
}

Rever is an optional interface that may be implemented by a database. If not implemented by the driver, the Get method will be used to emulate the functionality.

type Row

type Row struct {
	// ID is the document ID of the result.
	ID string `json:"id"`
	// Key is the view key of the result. For built-in views, this is the same
	// as ID.
	Key json.RawMessage `json:"key"`
	// Value is the raw, un-decoded JSON value. For most built-in views (such as
	// /_all_docs), this is `{"rev":"X-xxx"}`.
	Value json.RawMessage `json:"value"`
	// Doc is the raw, un-decoded JSON document. This is only populated by views
	// which return docs, such as /_all_docs?include_docs=true.
	Doc json.RawMessage `json:"doc"`
}

Row is a generic view result row.

type Rows

type Rows interface {
	// Next is called to populate *Row with the values of the next row in a
	// result set.
	//
	// Next should return io.EOF when there are no more rows.
	Next(*Row) error
	// Close closes the rows iterator.
	Close() error
	// UpdateSeq is the update sequence of the database, if requested in the
	// result set.
	UpdateSeq() string
	// Offset is the offset where the result set starts.
	Offset() int64
	// TotalRows is the number of documents in the database/view.
	TotalRows() int64
}

Rows is an iterator over a view's results.

type RowsWarner

type RowsWarner interface {
	// Warning returns the warning generated by the query, if any.
	Warning() string
}

RowsWarner is an optional interface, which allows a rows iterator to return a non-fatal warning. This is intended for use by the /_find endpoint, which generates warnings when indexes don't exist.

type Security

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

Security represents a database security document.

type SequenceID

type SequenceID string

SequenceID is a CouchDB update sequence ID. This is just a string, but has a special JSON unmarshaler to work with both CouchDB 2.0.0 (which uses normal) strings for sequence IDs, and earlier versions (which use integers)

func (*SequenceID) UnmarshalJSON

func (id *SequenceID) UnmarshalJSON(data []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type Session

type Session struct {
	// Name is the name of the authenticated user.
	Name string
	// Roles is a list of roles the user belongs to.
	Roles []string
	// AuthenticationMethod is the authentication method that was used for this
	// session.
	AuthenticationMethod string
	// AuthenticationDB is the user database against which authentication was
	// performed.
	AuthenticationDB string
	// AuthenticationHandlers is a list of authentication handlers configured on
	// the server.
	AuthenticationHandlers []string
	// RawResponse is the raw JSON response sent by the server, useful for
	// custom backends which may provide additional fields.
	RawResponse json.RawMessage
}

Session is a copy of kivik.Session

type Sessioner

type Sessioner interface {
	// Session returns information about the authenticated user.
	Session(ctx context.Context) (*Session, error)
}

Sessioner is an optional interface that a client may satisfy to provide access to the authenticated session information.

type Version

type Version struct {
	// Version is the version number reported by the server or backend.
	Version string
	// Vendor is the vendor string reported by the server or backend.
	Vendor string
	// Features is a list of enabled, optional features.  This was added in
	// CouchDB 2.1.0, and can be expected to be empty for older versions.
	Features []string
	// RawResponse is the raw response body as returned by the server.
	RawResponse json.RawMessage
}

Version represents a server version response.