Overview ▹

Overview ▾

Package clientv3 implements the official Go etcd client for v3.

Create client using `clientv3.New`:

// expect dial time-out on ipv4 blackhole
_, err := clientv3.New(clientv3.Config{
	Endpoints:   []string{"http://254.0.0.1:12345"},
	DialTimeout: 2 * time.Second,
})

// etcd clientv3 >= v3.2.10, grpc/grpc-go >= v1.7.3
if err == context.DeadlineExceeded {
	// handle errors
}

// etcd clientv3 <= v3.2.9, grpc/grpc-go <= v1.2.1
if err == grpc.ErrClientConnTimeout {
	// handle errors
}

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 a client request timeout, wrap the context with context.WithTimeout:

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: e.g. when clock drifts in server-side before client's context deadline exceeded.

See https://github.com/etcd-io/etcd/blob/main/api/v3rpc/rpctypes/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 err == rpctypes.ErrEmptyKey {
		// client-side error: key is not provided
	} else if ev, ok := status.FromError(err); ok {
		code := ev.Code()
		if code == codes.DeadlineExceeded {
			// server-side context might have timed-out first (due to clock skew)
			// while original client-side context is not timed-out yet
		}
	} else {
		// bad cluster endpoints, which are not etcd servers
	}
}

go func() { cli.Close() }()
_, err := kvc.Get(ctx, "a")
if err != nil {
	// with etcd clientv3 <= v3.3
	if err == context.Canceled {
		// grpc balancer calls 'Get' with an inflight client.Close
	} else if err == grpc.ErrClientConnClosing { // <= gRCP v1.7.x
		// grpc balancer calls 'Get' after client.Close.
	}
	// with etcd clientv3 >= v3.4
	if clientv3.IsConnCanceled(err) {
		// gRPC client connection is closed
	}
}

The grpc load balancer is registered statically and is shared across etcd clients. To enable detailed load balancer logging, set the ETCD_CLIENT_DEBUG environment variable. E.g. "ETCD_CLIENT_DEBUG=1".

Name	Synopsis
..
clientv3util	Package clientv3util contains utility functions derived from clientv3.
concurrency	Package concurrency implements concurrency operations on top of etcd such as distributed locks, barriers, and elections.
credentials	Package credentials implements gRPC credential interface with etcd specific logic.
experimental
recipes	Package recipe contains experimental client-side distributed synchronization primitives.
leasing	Package leasing serves linearizable reads from a local cache by acquiring exclusive write access to keys through a client-side leasing protocol.
mirror	Package mirror implements etcd mirroring operations.
mock
mockserver	Package mockserver provides mock implementations for etcdserver's server interface.
namespace	Package namespace is a clientv3 wrapper that translates all keys to begin with a given prefix.
naming	Package naming provides:
endpoints
resolver
ordering	Package ordering is a clientv3 wrapper that caches response header revisions to detect ordering violations from stale responses.
snapshot	Package snapshot implements utilities around etcd snapshot.
yaml	Package yaml handles yaml-formatted clientv3 configuration data.

Package clientv3

Overview ▹

Overview ▾

Index ▹

Index ▾

Package files

Constants

Variables

func GetPrefixRangeEnd ¶

func IsConnCanceled ¶

func IsOptsWithFromKey ¶

func IsOptsWithPrefix ¶

func RetryAuthClient ¶

func RetryClusterClient ¶

func RetryKVClient ¶

func RetryLeaseClient ¶

func RetryMaintenanceClient ¶

func SetLogger ¶

func WithRequireLeader ¶

type AlarmMember ¶

type AlarmResponse ¶

type Auth ¶

func NewAuth ¶

func NewAuthFromAuthClient ¶

type AuthDisableResponse ¶

type AuthEnableResponse ¶

type AuthRoleAddResponse ¶

type AuthRoleDeleteResponse ¶

type AuthRoleGetResponse ¶

type AuthRoleGrantPermissionResponse ¶

type AuthRoleListResponse ¶

type AuthRoleRevokePermissionResponse ¶

type AuthStatusResponse ¶

type AuthUserAddResponse ¶

type AuthUserChangePasswordResponse ¶

type AuthUserDeleteResponse ¶

type AuthUserGetResponse ¶

type AuthUserGrantRoleResponse ¶

type AuthUserListResponse ¶

type AuthUserRevokeRoleResponse ¶

type AuthenticateResponse ¶

type Client ¶

func New ¶

func NewCtxClient ¶

func NewFromURL ¶

func NewFromURLs ¶

func (*Client) ActiveConnection ¶

func (*Client) Close ¶

func (*Client) Ctx ¶

func (*Client) Dial ¶

func (*Client) Endpoints ¶

func (*Client) GetLogger ¶

func (*Client) SetEndpoints ¶

func (*Client) Sync ¶

func (*Client) WithLogger ¶

type Cluster ¶

func NewCluster ¶

func NewClusterFromClusterClient ¶

type Cmp ¶

func Compare ¶

func CreateRevision ¶

func LeaseValue ¶

func ModRevision ¶

func Value ¶

func Version ¶

func (*Cmp) KeyBytes ¶

func (*Cmp) ValueBytes ¶

func (*Cmp) WithKeyBytes ¶

func (Cmp) WithPrefix ¶

func (Cmp) WithRange ¶

func (*Cmp) WithValueBytes ¶

type CompactOp ¶

func OpCompact ¶

type CompactOption ¶

func WithCompactPhysical ¶

type CompactResponse ¶

type CompareResult ¶

type CompareTarget ¶

type Config ¶

type DefragmentResponse ¶