README ¶
etcd/clientv3
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:2379", "localhost:22379", "localhost:32379"},
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
etcd uses cmd/vendor
directory to store external dependencies, which are
to be compiled into etcd release binaries. client
can be imported without
vendoring. For full compatibility, it is recommended to vendor builds using
etcd's vendored packages, using tools like godep, as in
vendor directories.
For more detail, please read Go vendor design.
Error Handling
etcd client returns 2 types of errors:
- context error: canceled or deadline exceeded.
- gRPC error: see api/v3rpc/rpctypes.
Here is the example code to handle client errors:
resp, err := kvc.Put(ctx, "", "")
if err != nil {
switch err {
case context.Canceled:
log.Fatalf("ctx is canceled by another routine: %v", err)
case context.DeadlineExceeded:
log.Fatalf("ctx is attached with a deadline is exceeded: %v", err)
case rpctypes.ErrEmptyKey:
log.Fatalf("client-side error: %v", err)
default:
log.Fatalf("bad cluster endpoints, which are not etcd servers: %v", err)
}
}
Examples
More code examples can be found at GoDoc.
Documentation ¶
Overview ¶
Package clientv3 implements the official Go etcd client for v3.
Create client using `clientv3.New`:
cli, err := clientv3.New(clientv3.Config{ Endpoints: []string{"localhost:2379", "localhost:22379", "localhost:32379"}, 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
The Client has internal state (watchers and leases), so Clients should be reused instead of created as needed. Clients are safe for concurrent use by multiple goroutines.
etcd client returns 2 types of errors:
- context error: canceled or deadline exceeded.
- 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 } }
Index ¶
- Constants
- Variables
- func WithRequireLeader(ctx context.Context) context.Context
- type AlarmMember
- type AlarmResponse
- type Auth
- type AuthDisableResponse
- type AuthEnableResponse
- type AuthRoleAddResponse
- type AuthRoleDeleteResponse
- type AuthRoleGetResponse
- type AuthRoleGrantPermissionResponse
- type AuthRoleListResponse
- type AuthRoleRevokePermissionResponse
- type AuthUserAddResponse
- type AuthUserChangePasswordResponse
- type AuthUserDeleteResponse
- type AuthUserGetResponse
- type AuthUserGrantRoleResponse
- type AuthUserListResponse
- type AuthUserRevokeRoleResponse
- type AuthenticateResponse
- type Client
- type Cluster
- type Cmp
- type CompactOp
- type CompactOption
- type CompactResponse
- type CompareResult
- type CompareTarget
- type Config
- type DefragmentResponse
- type DeleteResponse
- type Event
- type GetResponse
- type KV
- type Lease
- type LeaseGrantResponse
- type LeaseID
- type LeaseKeepAliveResponse
- type LeaseRevokeResponse
- type Logger
- type Maintenance
- type Member
- type MemberAddResponse
- type MemberListResponse
- type MemberRemoveResponse
- type MemberUpdateResponse
- type Op
- type OpOption
- func WithCountOnly() OpOption
- func WithFirstCreate() []OpOption
- func WithFirstKey() []OpOption
- func WithFirstRev() []OpOption
- func WithFromKey() OpOption
- func WithKeysOnly() OpOption
- func WithLastCreate() []OpOption
- func WithLastKey() []OpOption
- func WithLastRev() []OpOption
- func WithLease(leaseID LeaseID) OpOption
- func WithLimit(n int64) OpOption
- func WithPrefix() OpOption
- func WithProgressNotify() OpOption
- func WithRange(endKey string) OpOption
- func WithRev(rev int64) OpOption
- func WithSerializable() OpOption
- func WithSort(target SortTarget, order SortOrder) OpOption
- type OpResponse
- type PermissionType
- type PutResponse
- type SortOption
- type SortOrder
- type SortTarget
- type StatusResponse
- type Txn
- type TxnResponse
- type WatchChan
- type WatchResponse
- type Watcher
Examples ¶
- Package
- Auth
- Cluster (MemberAdd)
- Cluster (MemberList)
- Cluster (MemberRemove)
- Cluster (MemberUpdate)
- KV (Compact)
- KV (Delete)
- KV (Do)
- KV (Get)
- KV (GetSortedPrefix)
- KV (GetWithRev)
- KV (Put)
- KV (PutErrorHandling)
- KV (Txn)
- Lease (Grant)
- Lease (KeepAlive)
- Lease (KeepAliveOnce)
- Lease (Revoke)
- Maintenance (Defragment)
- Maintenance (Status)
- Watcher (Watch)
- Watcher (WatchWithPrefix)
- Watcher (WatchWithProgressNotify)
- Watcher (WatchWithRange)
Constants ¶
const ( PermRead = authpb.READ PermWrite = authpb.WRITE PermReadWrite = authpb.READWRITE )
const ( EventTypeDelete = mvccpb.DELETE EventTypePut = mvccpb.PUT )
Variables ¶
var (
ErrNoAvailableEndpoints = errors.New("etcdclient: no available endpoints")
)
Functions ¶
Types ¶
type AlarmMember ¶
type AlarmMember pb.AlarmMember
type AlarmResponse ¶
type AlarmResponse pb.AlarmResponse
type Auth ¶
type Auth interface { // AuthEnable enables auth of an etcd cluster. AuthEnable(ctx context.Context) (*AuthEnableResponse, error) // AuthDisable disables auth of an etcd cluster. AuthDisable(ctx context.Context) (*AuthDisableResponse, error) // UserAdd adds a new user to an etcd cluster. UserAdd(ctx context.Context, name string, password string) (*AuthUserAddResponse, error) // UserDelete deletes a user from an etcd cluster. UserDelete(ctx context.Context, name string) (*AuthUserDeleteResponse, error) // UserChangePassword changes a password of a user. UserChangePassword(ctx context.Context, name string, password string) (*AuthUserChangePasswordResponse, error) // UserGrantRole grants a role to a user. UserGrantRole(ctx context.Context, user string, role string) (*AuthUserGrantRoleResponse, error) // UserGet gets a detailed information of a user. UserGet(ctx context.Context, name string) (*AuthUserGetResponse, error) // UserList gets a list of all users. UserList(ctx context.Context) (*AuthUserListResponse, error) // UserRevokeRole revokes a role of a user. UserRevokeRole(ctx context.Context, name string, role string) (*AuthUserRevokeRoleResponse, error) // RoleAdd adds a new role to an etcd cluster. RoleAdd(ctx context.Context, name string) (*AuthRoleAddResponse, error) // RoleGrantPermission grants a permission to a role. RoleGrantPermission(ctx context.Context, name string, key, rangeEnd string, permType PermissionType) (*AuthRoleGrantPermissionResponse, error) // RoleGet gets a detailed information of a role. RoleGet(ctx context.Context, role string) (*AuthRoleGetResponse, error) // RoleList gets a list of all roles. RoleList(ctx context.Context) (*AuthRoleListResponse, error) // RoleRevokePermission revokes a permission from a role. RoleRevokePermission(ctx context.Context, role string, key, rangeEnd string) (*AuthRoleRevokePermissionResponse, error) // RoleDelete deletes a role. RoleDelete(ctx context.Context, role string) (*AuthRoleDeleteResponse, error) }
Example ¶
Output: etcdserver: permission denied root user permission: key "foo", range end "zoo"
type AuthDisableResponse ¶
type AuthDisableResponse pb.AuthDisableResponse
type AuthEnableResponse ¶
type AuthEnableResponse pb.AuthEnableResponse
type AuthRoleAddResponse ¶
type AuthRoleAddResponse pb.AuthRoleAddResponse
type AuthRoleDeleteResponse ¶
type AuthRoleDeleteResponse pb.AuthRoleDeleteResponse
type AuthRoleGetResponse ¶
type AuthRoleGetResponse pb.AuthRoleGetResponse
type AuthRoleGrantPermissionResponse ¶
type AuthRoleGrantPermissionResponse pb.AuthRoleGrantPermissionResponse
type AuthRoleListResponse ¶
type AuthRoleListResponse pb.AuthRoleListResponse
type AuthRoleRevokePermissionResponse ¶
type AuthRoleRevokePermissionResponse pb.AuthRoleRevokePermissionResponse
type AuthUserAddResponse ¶
type AuthUserAddResponse pb.AuthUserAddResponse
type AuthUserChangePasswordResponse ¶
type AuthUserChangePasswordResponse pb.AuthUserChangePasswordResponse
type AuthUserDeleteResponse ¶
type AuthUserDeleteResponse pb.AuthUserDeleteResponse
type AuthUserGetResponse ¶
type AuthUserGetResponse pb.AuthUserGetResponse
type AuthUserGrantRoleResponse ¶
type AuthUserGrantRoleResponse pb.AuthUserGrantRoleResponse
type AuthUserListResponse ¶
type AuthUserListResponse pb.AuthUserListResponse
type AuthUserRevokeRoleResponse ¶
type AuthUserRevokeRoleResponse pb.AuthUserRevokeRoleResponse
type AuthenticateResponse ¶
type AuthenticateResponse pb.AuthenticateResponse
type Client ¶
type Client struct { Cluster KV Lease Watcher Auth Maintenance // Username is a username for authentication Username string // Password is a password for authentication Password string // contains filtered or unexported fields }
Client provides and manages an etcd v3 client session.
func NewFromConfigFile ¶
NewFromConfigFile creates a new etcdv3 client from a configuration file.
func NewFromURL ¶
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) Ctx ¶
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().
type Cluster ¶
type Cluster interface { // MemberList lists the current cluster membership. MemberList(ctx context.Context) (*MemberListResponse, 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 (MemberList) ¶
Output: members: 3
Example (MemberRemove) ¶
Output:
Example (MemberUpdate) ¶
Output:
func NewCluster ¶
type CompactOp ¶
type CompactOp struct {
// contains filtered or unexported fields
}
CompactOp represents a compact operation.
func OpCompact ¶
func OpCompact(rev int64, opts ...CompactOption) CompactOp
OpCompact wraps slice CompactOption to create a CompactOp.
type CompactOption ¶
type CompactOption func(*CompactOp)
CompactOption configures compact operation.
func WithCompactPhysical ¶
func WithCompactPhysical() CompactOption
WithCompactPhysical makes compact RPC call wait until the compaction is physically applied to the local database such that compacted entries are totally removed from the backend database.
type CompactResponse ¶
type CompactResponse pb.CompactionResponse
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 // DialTimeout is the timeout for failing to establish a connection. DialTimeout time.Duration // TLS holds the client secure credentials, if any. TLS *tls.Config // Logger is the logger used by client library. Logger Logger // Username is a username for authentication Username string // Password is a password for authentication Password string }
type DefragmentResponse ¶
type DefragmentResponse pb.DefragmentResponse
type DeleteResponse ¶
type DeleteResponse pb.DeleteRangeResponse
type Event ¶
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, opts ...CompactOption) (*CompactResponse, 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: Deleted all keys: true
Example (Do) ¶
Output:
Example (Get) ¶
Output: foo : bar
Example (GetSortedPrefix) ¶
Output: key_2 : value key_1 : value key_0 : value
Example (GetWithRev) ¶
Output: foo : bar1
Example (Put) ¶
Output:
Example (PutErrorHandling) ¶
Output: client-side error: etcdserver: key is not provided
Example (Txn) ¶
Output: key : XYZ
type Lease ¶
type Lease interface { // Grant creates a new lease. Grant(ctx context.Context, ttl int64) (*LeaseGrantResponse, 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 (Grant) ¶
Output:
Example (KeepAlive) ¶
Output: ttl: 5
Example (KeepAliveOnce) ¶
Output: ttl: 5
Example (Revoke) ¶
Output: number of keys: 0
type LeaseGrantResponse ¶
type LeaseGrantResponse struct { *pb.ResponseHeader ID LeaseID TTL int64 Error string }
LeaseGrantResponse is used to convert the protobuf grant response.
type LeaseID ¶
type LeaseID int64
const ( // NoLease is a lease ID for the absence of a lease. NoLease LeaseID = 0 )
type LeaseKeepAliveResponse ¶
type LeaseKeepAliveResponse struct { *pb.ResponseHeader ID LeaseID TTL int64 }
LeaseKeepAliveResponse is used to convert the protobuf keepalive response.
type LeaseRevokeResponse ¶
type LeaseRevokeResponse pb.LeaseRevokeResponse
type Maintenance ¶
type Maintenance interface { // AlarmList gets all active alarms. AlarmList(ctx context.Context) (*AlarmResponse, error) // AlarmDisarm disarms a given alarm. AlarmDisarm(ctx context.Context, m *AlarmMember) (*AlarmResponse, error) // 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) // Status gets the status of the endpoint. Status(ctx context.Context, endpoint string) (*StatusResponse, error) // Snapshot provides a reader for a snapshot of a backend. Snapshot(ctx context.Context) (io.ReadCloser, error) }
Example (Defragment) ¶
Output:
Example (Status) ¶
Output:
func NewMaintenance ¶
func NewMaintenance(c *Client) Maintenance
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.
type OpOption ¶
type OpOption func(*Op)
OpOption configures Operations like Get, Put, Delete.
func WithCountOnly ¶
func WithCountOnly() OpOption
WithCountOnly makes the 'Get' request return only the count of keys.
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 the key in the argument.
func WithKeysOnly ¶
func WithKeysOnly() OpOption
WithKeysOnly makes the 'Get' request return only the keys and the corresponding values will be omitted.
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 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 ¶
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 ¶
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
}
func (OpResponse) Del ¶
func (op OpResponse) Del() *DeleteResponse
func (OpResponse) Get ¶
func (op OpResponse) Get() *GetResponse
func (OpResponse) Put ¶
func (op OpResponse) Put() *PutResponse
type PermissionType ¶
type PermissionType authpb.Permission_Type
func StrToPermissionType ¶
func StrToPermissionType(s string) (PermissionType, error)
type PutResponse ¶
type PutResponse pb.PutResponse
type SortOption ¶
type SortOption struct { Target SortTarget Order SortOrder }
type SortTarget ¶
type SortTarget int
const ( SortByKey SortTarget = iota SortByVersion SortByCreateRevision SortByModRevision SortByValue )
type StatusResponse ¶
type StatusResponse pb.StatusResponse
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) }
Txn is the interface that wraps mini-transactions.
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 []*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 // contains filtered or unexported fields }
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 'WithPrefix'. Watch(ctx context.Context, key string, opts ...OpOption) WatchChan // Close closes the watcher and cancels all watch requests. Close() error }
Example (Watch) ¶
Output:
Example (WatchWithPrefix) ¶
Output:
Example (WatchWithProgressNotify) ¶
Output:
Example (WatchWithRange) ¶
Output:
func NewWatcher ¶
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package concurrency implements concurrency operations on top of etcd such as distributed locks, barriers, and elections.
|
Package concurrency implements concurrency operations on top of etcd such as distributed locks, barriers, and elections. |
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. |
Package mirror implements etcd mirroring operations.
|
Package mirror implements etcd mirroring operations. |