README

etcd/clientv3

Godoc

etcd/clientv3 is the official Go etcd client for v3.

Install

go get github.com/coreos/etcd/clientv3

Get started

Create client using clientv3.New:

cli, err := clientv3.New(clientv3.Config{
	Endpoints:   []string{"localhost:12378", "localhost:22378", "localhost:32378"},
	DialTimeout: 5 * time.Second,
})
if err != nil {
	// handle error!
}
defer cli.Close()

etcd v3 uses gRPC for remote procedure calls. And clientv3 uses grpc-go to connect to etcd. Make sure to close the client after using it. If the client is not closed, the connection will have leaky goroutines. To specify client request timeout, pass context.WithTimeout to APIs:

ctx, cancel := context.WithTimeout(context.Background(), timeout)
resp, err := kvc.Put(ctx, "sample_key", "sample_value")
cancel()
if err != nil {
    // handle error!
}
// use the response

Error Handling

etcd client returns 2 types of errors:

  1. context error: canceled or deadline exceeded.
  2. gRPC error: see v3rpc/error.

Here is the example code to handle client errors:

resp, err := kvc.Put(ctx, "", "")
if err != nil {
	if err == context.Canceled {
		// ctx is canceled by another routine
	} else if err == context.DeadlineExceeded {
		// ctx is attached with a deadline and it exceeded
	} else if verr, ok := err.(*v3rpc.ErrEmptyKey); ok {
		// process (verr.Errors)
	} else {
		// bad cluster endpoints, which are not etcd servers
	}
}

Examples

More code examples can be found at GoDoc.

Documentation

Overview

    clientv3 is the official Go etcd client for v3.

    Create client using `clientv3.New`:

    cli, err := clientv3.New(clientv3.Config{
    	Endpoints:   []string{"localhost:12378", "localhost:22378", "localhost:32378"},
    	DialTimeout: 5 * time.Second,
    })
    if err != nil {
    	// handle error!
    }
    defer cli.Close()
    

    Make sure to close the client after using it. If the client is not closed, the connection will have leaky goroutines.

    To specify client request timeout, pass context.WithTimeout to APIs:

    ctx, cancel := context.WithTimeout(context.Background(), timeout)
    resp, err := kvc.Put(ctx, "sample_key", "sample_value")
    cancel()
    if err != nil {
        // handle error!
    }
    // use the response
    

    etcd client returns 2 types of errors:

    1. context error: canceled or deadline exceeded.
    2. gRPC error: see https://github.com/coreos/etcd/blob/master/etcdserver/api/v3rpc/error.go.
    

    Here is the example code to handle client errors:

    resp, err := kvc.Put(ctx, "", "")
    if err != nil {
    	if err == context.Canceled {
    		// ctx is canceled by another routine
    	} else if err == context.DeadlineExceeded {
    		// ctx is attached with a deadline and it exceeded
    	} else if verr, ok := err.(*v3rpc.ErrEmptyKey); ok {
    		// process (verr.Errors)
    	} else {
    		// bad cluster endpoints, which are not etcd servers
    	}
    }
    
    Example
    Output:
    
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	ErrNoAvailableEndpoints = errors.New("etcdclient: no available endpoints")
    )

    Functions

    This section is empty.

    Types

    type Auth

    type Auth interface {
    	// AuthEnable enables auth of a etcd cluster.
    	AuthEnable(ctx context.Context) (*AuthEnableResponse, error)
    }

    func NewAuth

    func NewAuth(c *Client) Auth

    type AuthEnableResponse

    type AuthEnableResponse pb.AuthEnableResponse

    type Client

    type Client struct {
    	Cluster
    	KV
    	Lease
    	Watcher
    	Auth
    	Maintenance
    	// 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 NewFromURL

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

          NewFromURL creates a new etcdv3 client from a URL.

          func (*Client) ActiveConnection

          func (c *Client) ActiveConnection() *grpc.ClientConn

            ActiveConnection returns the current in-use connection

            func (*Client) Close

            func (c *Client) Close() error

              Close shuts down the client's etcd connections.

              func (*Client) Ctx

              func (c *Client) Ctx() context.Context

                Ctx is a context for "out of band" messages (e.g., for sending "clean up" message when another context is canceled). It is canceled on client Close().

                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 Cluster

                      type Cluster interface {
                      	// MemberList lists the current cluster membership.
                      	MemberList(ctx context.Context) (*MemberListResponse, error)
                      
                      	// MemberLeader returns the current leader member.
                      	MemberLeader(ctx context.Context) (*Member, error)
                      
                      	// MemberAdd adds a new member into the cluster.
                      	MemberAdd(ctx context.Context, peerAddrs []string) (*MemberAddResponse, error)
                      
                      	// MemberRemove removes an existing member from the cluster.
                      	MemberRemove(ctx context.Context, id uint64) (*MemberRemoveResponse, error)
                      
                      	// MemberUpdate updates the peer addresses of the member.
                      	MemberUpdate(ctx context.Context, id uint64, peerAddrs []string) (*MemberUpdateResponse, error)
                      }
                      Example (MemberAdd)
                      Output:
                      
                      
                      Example (MemberLeader)
                      Output:
                      
                      
                      Example (MemberList)
                      Output:
                      
                      
                      Example (MemberRemove)
                      Output:
                      
                      
                      Example (MemberUpdate)
                      Output:
                      
                      

                      func NewCluster

                      func NewCluster(c *Client) Cluster

                      type Cmp

                      type Cmp pb.Compare

                      func Compare

                      func Compare(cmp Cmp, result string, v interface{}) Cmp

                      func CreatedRevision

                      func CreatedRevision(key string) Cmp

                      func ModifiedRevision

                      func ModifiedRevision(key string) Cmp

                      func Value

                      func Value(key string) Cmp

                      func Version

                      func Version(key string) 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
                      
                      	// TLS holds the client secure credentials, if any.
                      	TLS *tls.Config
                      }

                      type DefragmentResponse

                      type DefragmentResponse pb.DefragmentResponse

                      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(ctx context.Context, key, val string, opts ...OpOption) (*PutResponse, error)
                        
                        	// Get retrieves keys.
                        	// By default, Get will return the value for "key", if any.
                        	// When passed WithRange(end), Get will return the keys in the range [key, end).
                        	// When passed WithFromKey(), Get returns keys greater than or equal to key.
                        	// When passed WithRev(rev) with rev > 0, Get retrieves keys at the given revision;
                        	// if the required revision is compacted, the request will fail with ErrCompacted .
                        	// When passed WithLimit(limit), the number of returned keys is bounded by limit.
                        	// When passed WithSort(), the keys will be sorted.
                        	Get(ctx context.Context, key string, opts ...OpOption) (*GetResponse, error)
                        
                        	// Delete deletes a key, or optionally using WithRange(end), [key, end).
                        	Delete(ctx context.Context, key string, opts ...OpOption) (*DeleteResponse, error)
                        
                        	// Compact compacts etcd KV history before the given rev.
                        	Compact(ctx context.Context, rev int64) error
                        
                        	// Do applies a single Op on KV without a transaction.
                        	// Do is useful when creating arbitrary operations to be issued at a
                        	// later time; the user can range over the operations, calling Do to
                        	// execute them. Get/Put/Delete, on the other hand, are best suited
                        	// for when the	operation should be issued at the time of declaration.
                        	Do(ctx context.Context, op Op) (OpResponse, error)
                        
                        	// Txn creates a transaction.
                        	Txn(ctx context.Context) Txn
                        }
                        Example (Compact)
                        Output:
                        
                        
                        Example (Delete)
                        Output:
                        
                        
                        Example (Do)
                        Output:
                        
                        
                        Example (Get)
                        Output:
                        
                        
                        Example (GetSortedPrefix)
                        Output:
                        
                        
                        Example (Put)
                        Output:
                        
                        
                        Example (Txn)
                        Output:
                        
                        

                        func NewKV

                        func NewKV(c *Client) KV

                        type Lease

                        type Lease interface {
                        	// Create creates a new lease.
                        	Create(ctx context.Context, ttl int64) (*LeaseCreateResponse, error)
                        
                        	// Revoke revokes the given lease.
                        	Revoke(ctx context.Context, id LeaseID) (*LeaseRevokeResponse, error)
                        
                        	// KeepAlive keeps the given lease alive forever.
                        	KeepAlive(ctx context.Context, id 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 LeaseID) (*LeaseKeepAliveResponse, error)
                        
                        	// Close releases all resources Lease keeps for efficient communication
                        	// with the etcd server.
                        	Close() error
                        }
                        Example (Create)
                        Output:
                        
                        
                        Example (KeepAlive)
                        Output:
                        
                        
                        Example (KeepAliveOnce)
                        Output:
                        
                        
                        Example (Revoke)
                        Output:
                        
                        

                        func NewLease

                        func NewLease(c *Client) Lease

                        type LeaseCreateResponse

                        type LeaseCreateResponse pb.LeaseCreateResponse

                        type LeaseID

                        type LeaseID int64
                        const (
                        
                        	// NoLease is a lease ID for the absence of a lease.
                        	NoLease LeaseID = 0
                        )

                        type LeaseKeepAliveResponse

                        type LeaseKeepAliveResponse pb.LeaseKeepAliveResponse

                        type LeaseRevokeResponse

                        type LeaseRevokeResponse pb.LeaseRevokeResponse

                        type Maintenance

                        type Maintenance interface {
                        	// Defragment defragments storage backend of the etcd member with given endpoint.
                        	// Defragment is only needed when deleting a large number of keys and want to reclaim
                        	// the resources.
                        	// Defragment is an expensive operation. User should avoid defragmenting multiple members
                        	// at the same time.
                        	// To defragment multiple members in the cluster, user need to call defragment multiple
                        	// times with different endpoints.
                        	Defragment(ctx context.Context, endpoint string) (*DefragmentResponse, error)
                        }

                        type Member

                        type Member pb.Member

                        type MemberAddResponse

                        type MemberAddResponse pb.MemberAddResponse

                        type MemberListResponse

                        type MemberListResponse pb.MemberListResponse

                        type MemberRemoveResponse

                        type MemberRemoveResponse pb.MemberRemoveResponse

                        type MemberUpdateResponse

                        type MemberUpdateResponse pb.MemberUpdateResponse

                        type Op

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

                          Op represents an Operation that kv can execute.

                          func OpDelete

                          func OpDelete(key string, opts ...OpOption) Op

                          func OpGet

                          func OpGet(key string, opts ...OpOption) Op

                          func OpPut

                          func OpPut(key, val string, opts ...OpOption) Op

                          type OpOption

                          type OpOption func(*Op)

                            OpOption configures Operations like Get, Put, Delete.

                            func WithFirstCreate

                            func WithFirstCreate() []OpOption

                              WithFirstCreate gets the key with the oldest creation revision in the request range.

                              func WithFirstKey

                              func WithFirstKey() []OpOption

                                WithFirstKey gets the lexically first key in the request range.

                                func WithFirstRev

                                func WithFirstRev() []OpOption

                                  WithFirstRev gets the key with the oldest modification revision in the request range.

                                  func WithFromKey

                                  func WithFromKey() OpOption

                                    WithFromKey specifies the range of 'Get' or 'Delete' requests to be equal or greater than they key in the argument.

                                    func WithLastCreate

                                    func WithLastCreate() []OpOption

                                      WithLastCreate gets the key with the latest creation revision in the request range.

                                      func WithLastKey

                                      func WithLastKey() []OpOption

                                        WithLastKey gets the lexically last key in the request range.

                                        func WithLastRev

                                        func WithLastRev() []OpOption

                                          WithLastRev gets the key with the latest modification revision in the request range.

                                          func WithLease

                                          func WithLease(leaseID LeaseID) OpOption

                                            WithLease attaches a lease ID to a key in 'Put' request.

                                            func WithLimit

                                            func WithLimit(n int64) OpOption

                                              WithLimit limits the number of results to return from 'Get' request.

                                              func WithPrefix

                                              func WithPrefix() OpOption

                                                WithPrefix enables 'Get', 'Delete', or 'Watch' requests to operate on the keys with matching prefix. For example, 'Get(foo, WithPrefix())' can return 'foo1', 'foo2', and so on.

                                                func WithProgressNotify

                                                func WithProgressNotify() OpOption

                                                  WithProgressNotify makes watch server send periodic progress updates. Progress updates have zero events in WatchResponse.

                                                  func WithRange

                                                  func WithRange(endKey string) OpOption

                                                    WithRange specifies the range of 'Get' or 'Delete' requests. For example, 'Get' requests with 'WithRange(end)' returns the keys in the range [key, end).

                                                    func WithRev

                                                    func WithRev(rev int64) OpOption

                                                      WithRev specifies the store revision for 'Get' request. Or the start revision of 'Watch' request.

                                                      func WithSerializable

                                                      func WithSerializable() OpOption

                                                        WithSerializable makes 'Get' request serializable. By default, it's linearizable. Serializable requests are better for lower latency requirement.

                                                        func WithSort

                                                        func WithSort(target SortTarget, order SortOrder) OpOption

                                                          WithSort specifies the ordering in 'Get' request. It requires 'WithRange' and/or 'WithPrefix' to be specified too. 'target' specifies the target to sort by: key, version, revisions, value. 'order' can be either 'SortNone', 'SortAscend', 'SortDescend'.

                                                          type OpResponse

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

                                                          type PutResponse

                                                          type PutResponse pb.PutResponse

                                                          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 WatchChan

                                                            type WatchChan <-chan WatchResponse

                                                            type WatchResponse

                                                            type WatchResponse struct {
                                                            	Header pb.ResponseHeader
                                                            	Events []*storagepb.Event
                                                            
                                                            	// CompactRevision is the minimum revision the watcher may receive.
                                                            	CompactRevision int64
                                                            
                                                            	// Canceled is used to indicate watch failure.
                                                            	// If the watch failed and the stream was about to close, before the channel is closed,
                                                            	// the channel sends a final response that has Canceled set to true with a non-nil Err().
                                                            	Canceled bool
                                                            }

                                                            func (*WatchResponse) Err

                                                            func (wr *WatchResponse) Err() error

                                                              Err is the error value if this WatchResponse holds an error.

                                                              func (*WatchResponse) IsProgressNotify

                                                              func (wr *WatchResponse) IsProgressNotify() bool

                                                                IsProgressNotify returns true if the WatchResponse is progress notification.

                                                                type Watcher

                                                                type Watcher interface {
                                                                	// Watch watches on a key or 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.
                                                                	// 'opts' can be: 'WithRev' and/or 'WitchPrefix'.
                                                                	Watch(ctx context.Context, key string, opts ...OpOption) WatchChan
                                                                
                                                                	// Close closes the watcher and cancels all watch requests.
                                                                	Close() error
                                                                }
                                                                Example (Watch)
                                                                Output:
                                                                
                                                                
                                                                Example (WatchPrefix)
                                                                Output:
                                                                
                                                                
                                                                Example (WatchProgressNotify)
                                                                Output:
                                                                
                                                                

                                                                func NewWatcher

                                                                func NewWatcher(c *Client) Watcher

                                                                Directories

                                                                Path Synopsis
                                                                Package integration implements tests built upon embedded etcd, and focuses on correctness of etcd client.
                                                                Package integration implements tests built upon embedded etcd, and focuses on correctness of etcd client.