kivik: github.com/go-kivik/kivik/driver Index | Files

package driver

import "github.com/go-kivik/kivik/driver"

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

Most code should use package kivik.

Index

Package Files

changes.go doc.go driver.go rows.go session.go updates.go

type Attachment Uses

type Attachment struct {
    Filename        string        `json:"-"`
    ContentType     string        `json:"content_type"`
    Stub            bool          `json:"stub"`
    Content         io.ReadCloser `json:"-"`
    Size            int64         `json:"length"`
    ContentEncoding string        `json:"encoding"`
    EncodedLength   int64         `json:"encoded_length"`
    RevPos          int64         `json:"revpos"`
    Digest          string        `json:"digest"`
}

Attachment represents a file attachment to a document.

type AttachmentMetaGetter Uses

type AttachmentMetaGetter interface {
    // GetAttachmentMetaOpts returns meta information about an attachment.
    GetAttachmentMeta(ctx context.Context, docID, rev, filename string, options map[string]interface{}) (*Attachment, error)
}

AttachmentMetaGetter 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 Attachments Uses

type Attachments interface {
    // Next is called to pupulate att with the next attachment in the result
    // set.
    //
    //
    // Next should return io.EOF when there are no more attachments.
    Next(att *Attachment) error

    // Close closes the Attachments iterator
    Close() error
}

Attachments is an iterator over the attachments included in a document when Get is called with `include_docs=true`.

type Authenticator Uses

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 Uses

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 that may be implemented by a Rows for returning a paging bookmark.

type BulkDocer Uses

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 DB 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, with options passed through unaltered.

type BulkResult Uses

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 Uses

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 Uses

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 Uses

type ChangedRevs []string

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

func (*ChangedRevs) UnmarshalJSON Uses

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

UnmarshalJSON satisfies the json.Unmarshaler interface

type Changes Uses

type Changes interface {
    // Next is called to populate *Change with 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 Uses

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 Uses

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 ClusterStats Uses

type ClusterStats struct {
    Replicas    int `json:"n"`
    Shards      int `json:"q"`
    ReadQuorum  int `json:"r"`
    WriteQuorum int `json:"w"`
}

ClusterStats contains the cluster configuration for the database.

type Copier Uses

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, the functionality will be emulated by calling Get followed by Put, with options passed through unaltered, except that the 'rev' option will be removed for the Put call.

type DB Uses

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 returns the
    // content length (or -1 if unknown), and an io.ReadCloser to access the
    // raw JSON content.
    Get(ctx context.Context, docID string, options map[string]interface{}) (*Document, error)
    // CreateDoc creates a new doc, with a server-generated ID.
    CreateDoc(ctx context.Context, doc interface{}, options map[string]interface{}) (docID, rev string, err error)
    // Put writes the document in the database.
    Put(ctx context.Context, docID string, doc interface{}, options map[string]interface{}) (rev string, err error)
    // Delete marks the specified document as deleted.
    Delete(ctx context.Context, docID, rev string, options map[string]interface{}) (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 string, att *Attachment, options map[string]interface{}) (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, options map[string]interface{}) (*Attachment, error)
    // DeleteAttachment deletes an attachment from a document, returning the
    // document's new revision.
    DeleteAttachment(ctx context.Context, docID, rev, filename string, options map[string]interface{}) (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 DBStats Uses

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:"-"`
    Cluster        *ClusterStats   `json:"cluster,omitempty"`
    RawResponse    json.RawMessage `json:"-"`
}

DBStats contains database statistics.

type DBUpdate Uses

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

DBUpdate represents a database update event.

type DBUpdater Uses

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 Uses

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 DBsStatser Uses

type DBsStatser interface {
    // DBsStats returns database statistical information for each database
    // named in dbNames. The returned values should be in the same order as
    // the requested database names, and any missing databases should return
    // a nil *DBStats value.
    DBsStats(ctx context.Context, dbNames []string) ([]*DBStats, error)
}

DBsStatser is an optional interface, added to support CouchDB 2.2.0's /_dbs_info endpoint. If this is not supported, or if this method returns status 404, Kivik will fall back to calling the method of issuing a GET /{db} for each database requested.

type DesignDocer Uses

type DesignDocer interface {
    // DesignDocs returns all of the design documents in the database, subject
    // to the options provided.
    DesignDocs(ctx context.Context, options map[string]interface{}) (Rows, error)
}

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

type Document Uses

type Document struct {
    // ContentLength is the size of the document response in bytes.
    ContentLength int64

    // Rev is the revision number returned
    Rev string

    // Body contains the respons body, either in raw JSON or multipart/related
    // format.
    Body io.ReadCloser

    // Attachments will be nil except when include_docs=true.
    Attachments Attachments
}

Document represents a single document returned by Get

type Driver Uses

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

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

type Finder Uses

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
    // Explain returns the query plan for a given query. Explain takes the same
    // arguments as Find.
    Explain(ctx context.Context, query interface{}) (*QueryPlan, error)
}

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

type Flusher Uses

type Flusher 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
}

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

type Index Uses

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 LocalDocer Uses

type LocalDocer interface {
    // LocalDocs returns all of the local documents in the database, subject to
    // the options provided.
    LocalDocs(ctx context.Context, options map[string]interface{}) (Rows, error)
}

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

type Members Uses

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

Members represents the members of a database security document.

type MetaGetter Uses

type MetaGetter interface {
    // GetMeta returns the document size and revision of the requested document.
    // GetMeta should accept the same options as the Get method.
    GetMeta(ctx context.Context, docID string, options map[string]interface{}) (size int64, rev string, err error)
}

MetaGetter is an optional interface that may be implemented by a DB. If not implemented, the Get method will be used to emulate the functionality, with options passed through unaltered.

type PurgeResult Uses

type PurgeResult struct {
    Seq    int64               `json:"purge_seq"`
    Purged map[string][]string `json:"purged"`
}

PurgeResult is the result of a purge request.

type Purger Uses

type Purger interface {
    // Purge permanently removes the references to deleted documents from the
    // database.
    Purge(ctx context.Context, docRevMap map[string][]string) (*PurgeResult, error)
}

Purger is an optional interface which may be implemented by a DB to support document purging.

type QueryPlan Uses

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 Uses

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 Uses

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 Row Uses

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"`
    // Error represents the error for any row not fetched. Usually just
    // 'not_found'.
    Error error `json:"-"`
}

Row is a generic view result row.

type Rows Uses

type Rows interface {
    // Next is called to populate row with the next row in the result set.
    //
    // Next should return io.EOF when there are no more rows.
    Next(row *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 Uses

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

RowsWarner is an optional interface that may be implemented by a Rows, 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 Uses

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

Security represents a database security document.

type SequenceID Uses

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 Uses

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

UnmarshalJSON satisfies the json.Unmarshaler interface.

type Session Uses

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 Uses

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 Uses

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.

Package driver imports 5 packages (graph) and is imported by 9 packages. Updated 2018-11-11. Refresh now. Tools for package owners.