Skip to content
Branch: master
Find file History
jpbetz Merge pull request #11211 from jpbetz/ipv6-endpoints
Replace endpoint.ParseHostPort with net.SplitHostPort to fix IPv6 client endpoints
Latest commit 6aae903 Oct 9, 2019
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
balancer Replace endpoint.ParseHostPort with net.SplitHostPort to fix IPv6 cli… Oct 8, 2019
clientv3util *: revert module import paths May 28, 2019
concurrency clientv3/concurrency: remove the unneeded slash Sep 18, 2019
credentials clientv3: Set authority used in cert checks to host of endpoint Sep 25, 2019
integration integration: fix bug in for loop, make it break properly Sep 17, 2019
leasing test: test update for Go 1.12.5 and related changes Jun 5, 2019
mirror test: test update for Go 1.12.5 and related changes Jun 5, 2019
namespace *: revert module import paths May 28, 2019
naming *: revert module import paths May 28, 2019
ordering *: revert module import paths May 28, 2019
snapshot etcdserver: add put request steps. Oct 1, 2019
yaml *: revert module import paths May 28, 2019
README.md *: move to etcd.io for docs May 20, 2019
auth.go *: support creating a user without password May 30, 2019
client.go Replace endpoint.ParseHostPort with net.SplitHostPort to fix IPv6 cli… Oct 8, 2019
client_test.go clientv3: add nil checks in Close() Aug 21, 2019
cluster.go *: revert module import paths May 28, 2019
compact_op.go *: revert module import paths May 28, 2019
compact_op_test.go *: revert module import paths May 28, 2019
compare.go *: revert module import paths May 28, 2019
config.go clientv3: document "WithBlock" dial option Aug 5, 2019
doc.go clientv3: deprecate "grpc.ErrClientConnClosing" Aug 5, 2019
example_auth_test.go *: revert module import paths May 28, 2019
example_cluster_test.go *: revert module import paths May 28, 2019
example_kv_test.go clientv3: remove the redundant CancelFunc invocation Sep 18, 2019
example_lease_test.go *: revert module import paths May 28, 2019
example_maintenance_test.go *: revert module import paths May 28, 2019
example_metrics_test.go *: revert module import paths May 28, 2019
example_test.go *: revert module import paths May 28, 2019
example_watch_test.go *: revert module import paths May 28, 2019
kv.go *: revert module import paths May 28, 2019
lease.go *: revert module import paths May 28, 2019
logger.go *: revert module import paths May 28, 2019
main_test.go *: revert module import paths May 28, 2019
maintenance.go *: revert module import paths May 28, 2019
op.go test: test update for Go 1.12.5 and related changes Jun 5, 2019
op_test.go *: revert module import paths May 28, 2019
options.go test: test update for Go 1.12.5 and related changes Jun 5, 2019
retry.go test: test update for Go 1.12.5 and related changes Jun 5, 2019
retry_interceptor.go test: test update for Go 1.12.5 and related changes Jun 5, 2019
sort.go clientv3: update LICENSE header May 13, 2016
txn.go *: revert module import paths May 28, 2019
txn_test.go *: revert module import paths May 28, 2019
utils.go clientV3: fix behavior of WithPrefix and WithFromKey functions Feb 27, 2019
watch.go Fixed a missing block bug Jun 28, 2019
watch_test.go *: revert module import paths May 28, 2019

README.md

etcd/clientv3

Docs Godoc

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

Install

go get go.etcd.io/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 := cli.Put(ctx, "sample_key", "sample_value")
cancel()
if err != nil {
    // handle error!
}
// use the response

For full compatibility, it is recommended to vendor builds using etcd's vendored packages, using tools like golang/dep, as in vendor directories.

Error Handling

etcd client returns 2 types of errors:

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

Here is the example code to handle client errors:

resp, err := cli.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)
	}
}

Metrics

The etcd client optionally exposes RPC metrics through go-grpc-prometheus. See the examples.

Namespacing

The namespace package provides clientv3 interface wrappers to transparently isolate client requests to a user-defined prefix.

Request size limit

Client request size limit is configurable via clientv3.Config.MaxCallSendMsgSize and MaxCallRecvMsgSize in bytes. If none given, client request send limit defaults to 2 MiB including gRPC overhead bytes. And receive limit defaults to math.MaxInt32.

Examples

More code examples can be found at GoDoc.

You can’t perform that action at this time.