clientv3

Documentation

Overview

Copyright 2016 CoreOS, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• func CreatedRevision(key string) (string, pb.Compare_CompareTarget)
• func ModifiedRevision(key string) (string, pb.Compare_CompareTarget)
• func Value(key string) (string, pb.Compare_CompareTarget)
• func Version(key string) (string, pb.Compare_CompareTarget)
• type Client
  • func New(cfg Config) (*Client, error)
  • func NewFromConn(conn *grpc.ClientConn) *Client
  • func NewFromURL(url string) (*Client, error)
  • func (c *Client) Clone() *Client
  • func (c *Client) Close() error
  • func (c *Client) Dial(endpoint string) (*grpc.ClientConn, error)
  • func (c *Client) Endpoints() []string
  • func (c *Client) Errors() (errs []error)
• type Cmp
  • func Compare(key string, t pb.Compare_CompareTarget, result string, v interface{}) Cmp
• type CompareResult
• type CompareTarget
• type Config
• type DeleteRangeResponse
• type DeleteResponse
• type EndpointDialer
• type GetResponse
• type KV
  • func NewKV(c *Client) KV
• type Lease
• type LeaseCreateResponse
• type LeaseKeepAliveResponse
• type LeaseRevokeResponse
• type Op
  • func OpDelete(key string) Op
  • func OpDeleteRange(key, end string) Op
  • func OpGet(key string, rev int64) Op
  • func OpPut(key, val string, leaseID lease.LeaseID) Op
  • func OpRange(key, end string, limit, rev int64, sort *SortOption) Op
• type PutResponse
• type RangeResponse
• type SortOption
• type SortOrder
• type SortTarget
• type Txn
• type TxnResponse
• type WatchResponse
• type Watcher

Functions

func CreatedRevision

func CreatedRevision(key string) (string, pb.Compare_CompareTarget)

func ModifiedRevision

func ModifiedRevision(key string) (string, pb.Compare_CompareTarget)

func Value

func Value(key string) (string, pb.Compare_CompareTarget)

func Version

func Version(key string) (string, pb.Compare_CompareTarget)

Types

type Client

type Client struct {
	// KV is the keyvalue API for the client's connection.
	KV pb.KVClient
	// Lease is the lease API for the client's connection.
	Lease pb.LeaseClient
	// Watch is the watch API for the client's connection.
	Watch pb.WatchClient
	// Cluster is the cluster API for the client's connection.
	Cluster pb.ClusterClient
	// contains filtered or unexported fields
}

Client provides and manages an etcd v3 client session.

func New

func New(cfg Config) (*Client, error)

New creates a new etcdv3 client from a given configuration.

func NewFromConn

func NewFromConn(conn *grpc.ClientConn) *Client

NewFromConn creates a new etcdv3 client from an established grpc Connection.

func NewFromURL

func NewFromURL(url string) (*Client, error)

NewFromURL creates a new etcdv3 client from a URL.

func (*Client) Clone

func (c *Client) Clone() *Client

Clone creates a copy of client with the old connection and new API clients.

func (*Client) Close

func (c *Client) Close() error

Close shuts down the client's etcd connections.

func (*Client) Dial

func (c *Client) Dial(endpoint string) (*grpc.ClientConn, error)

Dial establishes a connection for a given endpoint using the client's config

func (*Client) Endpoints

func (c *Client) Endpoints() []string

Endpoints lists the registered endpoints for the client.

func (*Client) Errors

func (c *Client) Errors() (errs []error)

Errors returns all errors that have been observed since called last.

type Cmp

type Cmp pb.Compare

func Compare

func Compare(key string, t pb.Compare_CompareTarget, result string, v interface{}) Cmp

type CompareResult

type CompareResult int

type CompareTarget

type CompareTarget int

const (
	CompareVersion CompareTarget = iota
	CompareCreated
	CompareModified
	CompareValue
)

type Config

type Config struct {
	// Endpoints is a list of URLs
	Endpoints []string

	// RetryDialer chooses the next endpoint to use
	RetryDialer EndpointDialer

	// DialTimeout is the timeout for failing to establish a connection.
	DialTimeout time.Duration
}

type DeleteRangeResponse

type DeleteRangeResponse pb.DeleteRangeResponse

type DeleteResponse

type DeleteResponse pb.DeleteRangeResponse

type EndpointDialer

type EndpointDialer func(*Client) (*grpc.ClientConn, error)

EndpointDialer is a policy for choosing which endpoint to dial next

type GetResponse

type GetResponse pb.RangeResponse

type KV

type KV interface {
	// PUT puts a key-value pair into etcd.
	// Note that key,value can be plain bytes array and string is
	// an immutable representation of that bytes array.
	// To get a string of bytes, do string([]byte(0x10, 0x20)).
	Put(key, val string, leaseID lease.LeaseID) (*PutResponse, error)

	// Range gets the keys [key, end) in the range at rev.
	// If revev <=0, range gets the keys at currentRev.
	// Limit limits the number of keys returned.
	// If the required rev is compacted, ErrCompacted will be returned.
	Range(key, end string, limit, rev int64, sort *SortOption) (*RangeResponse, error)

	// Get is like Range. A shortcut for ranging single key like [key, key+1).
	Get(key string, rev int64) (*GetResponse, error)

	// DeleteRange deletes the given range [key, end).
	DeleteRange(key, end string) (*DeleteRangeResponse, error)

	// Delete is like DeleteRange. A shortcut for deleting single key like [key, key+1).
	Delete(key string) (*DeleteResponse, error)

	// Compact compacts etcd KV history before the given rev.
	Compact(rev int64) error

	// Txn creates a transaction.
	Txn() Txn
}

func NewKV

func NewKV(c *Client) KV

type Lease

type Lease interface {
	// Create creates a new lease.
	Create(ctx context.Context, ttl int64) *LeaseCreateResponse

	// Revoke revokes the given lease.
	Revoke(ctx context.Context, id lease.LeaseID) *LeaseRevokeResponse

	// KeepAlive keeps the given lease alive forever.
	KeepAlive(ctx context.Context, id lease.LeaseID) (chan<- *LeaseKeepAliveResponse, error)

	// KeepAliveOnce renews the lease once. In most of the cases, Keepalive
	// should be used instead of KeepAliveOnce.
	KeepAliveOnce(ctx context.Context, id lease.LeaseID) (*LeaseKeepAliveResponse, error)
}

type LeaseCreateResponse

type LeaseCreateResponse pb.LeaseCreateResponse

type LeaseKeepAliveResponse

type LeaseKeepAliveResponse pb.LeaseKeepAliveResponse

type LeaseRevokeResponse

type LeaseRevokeResponse pb.LeaseRevokeResponse

type Op

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

Op represents an Operation that kv can execute.

func OpDelete

func OpDelete(key string) Op

func OpDeleteRange

func OpDeleteRange(key, end string) Op

func OpGet

func OpGet(key string, rev int64) Op

func OpPut

func OpPut(key, val string, leaseID lease.LeaseID) Op

func OpRange

func OpRange(key, end string, limit, rev int64, sort *SortOption) Op

type PutResponse

type PutResponse pb.PutResponse

type RangeResponse

type RangeResponse pb.RangeResponse

type SortOption

type SortOption struct {
	Target SortTarget
	Order  SortOrder
}

type SortOrder

type SortOrder int

const (
	SortNone SortOrder = iota
	SortAscend
	SortDescend
)

type SortTarget

type SortTarget int

const (
	SortByKey SortTarget = iota
	SortByVersion
	SortByCreatedRev
	SortByModifiedRev
	SortByValue
)

type Txn

type Txn interface {
	// If takes a list of comparison. If all comparisons passed in succeed,
	// the operations passed into Then() will be executed. Or the operations
	// passed into Else() will be executed.
	If(cs ...Cmp) Txn

	// Then takes a list of operations. The Ops list will be executed, if the
	// comparisons passed in If() succeed.
	Then(ops ...Op) Txn

	// Else takes a list of operations. The Ops list will be executed, if the
	// comparisons passed in If() fail.
	Else(ops ...Op) Txn

	// Commit tries to commit the transaction.
	Commit() (*TxnResponse, error)
}

Tx.If(

Compare(Value(k1), ">", v1),
Compare(Version(k1), "=", 2)

).Then(

OpPut(k2,v2), OpPut(k3,v3)

).Else(

OpPut(k4,v4), OpPut(k5,v5)

).Commit()

type TxnResponse

type TxnResponse pb.TxnResponse

type WatchResponse

type WatchResponse struct {
	Header pb.ResponseHeader
	Events []*storagepb.Event
}

type Watcher

type Watcher interface {
	// Watch watches on a single key. The watched events will be returned
	// through the returned channel.
	// If the watch is slow or the required rev is compacted, the watch request
	// might be canceled from the server-side and the chan will be closed.
	Watch(cxt context.Context, key string, rev int64) <-chan WatchResponse

	// Watch watches on a prefix. The watched events will be returned
	// through the returned channel.
	// If the watch is slow or the required rev is compacted, the watch request
	// might be canceled from the server-side and the chan will be closed.
	WatchPrefix(cxt context.Context, prefix string, rev int64) <-chan WatchResponse

	// Close closes the watcher and cancels all watch requests.
	Close() error
}