Joe Betz 6aae90325c Merge pull request #11211 from jpbetz/ipv6-endpoints 5 years ago
..
balancer 594354b886 Replace endpoint.ParseHostPort with net.SplitHostPort to fix IPv6 client endpoints 5 years ago
clientv3util 34bd797e67 *: revert module import paths 5 years ago
concurrency e53298afb1 clientv3/concurrency: remove the unneeded slash 5 years ago
credentials 97388ce454 clientv3: Set authority used in cert checks to host of endpoint 5 years ago
integration 6287052bd0 integration: fix bug in for loop, make it break properly 5 years ago
leasing 1caaa9ed4a test: test update for Go 1.12.5 and related changes 5 years ago
mirror 1caaa9ed4a test: test update for Go 1.12.5 and related changes 5 years ago
namespace 34bd797e67 *: revert module import paths 5 years ago
naming 34bd797e67 *: revert module import paths 5 years ago
ordering 34bd797e67 *: revert module import paths 5 years ago
snapshot 401df4bb8e etcdserver: add put request steps. 5 years ago
yaml 34bd797e67 *: revert module import paths 5 years ago
README.md c5e5240004 *: move to etcd.io for docs 5 years ago
auth.go 5a67dd788d *: support creating a user without password 5 years ago
client.go 594354b886 Replace endpoint.ParseHostPort with net.SplitHostPort to fix IPv6 client endpoints 5 years ago
client_test.go 7f47de8414 clientv3: add nil checks in Close() 5 years ago
cluster.go 34bd797e67 *: revert module import paths 5 years ago
compact_op.go 34bd797e67 *: revert module import paths 5 years ago
compact_op_test.go 34bd797e67 *: revert module import paths 5 years ago
compare.go 34bd797e67 *: revert module import paths 5 years ago
config.go 4b0af5b4ac clientv3: document "WithBlock" dial option 5 years ago
doc.go 9b385737f5 clientv3: deprecate "grpc.ErrClientConnClosing" 5 years ago
example_auth_test.go 34bd797e67 *: revert module import paths 5 years ago
example_cluster_test.go 34bd797e67 *: revert module import paths 5 years ago
example_kv_test.go e24564224a clientv3: remove the redundant CancelFunc invocation 5 years ago
example_lease_test.go 34bd797e67 *: revert module import paths 5 years ago
example_maintenance_test.go 34bd797e67 *: revert module import paths 5 years ago
example_metrics_test.go 34bd797e67 *: revert module import paths 5 years ago
example_test.go 34bd797e67 *: revert module import paths 5 years ago
example_watch_test.go 34bd797e67 *: revert module import paths 5 years ago
kv.go 34bd797e67 *: revert module import paths 5 years ago
lease.go 34bd797e67 *: revert module import paths 5 years ago
logger.go 34bd797e67 *: revert module import paths 5 years ago
main_test.go 34bd797e67 *: revert module import paths 5 years ago
maintenance.go 34bd797e67 *: revert module import paths 5 years ago
op.go 1caaa9ed4a test: test update for Go 1.12.5 and related changes 5 years ago
op_test.go 34bd797e67 *: revert module import paths 5 years ago
options.go 1caaa9ed4a test: test update for Go 1.12.5 and related changes 5 years ago
retry.go 1caaa9ed4a test: test update for Go 1.12.5 and related changes 5 years ago
retry_interceptor.go 1caaa9ed4a test: test update for Go 1.12.5 and related changes 5 years ago
sort.go fd9e07a529 clientv3: update LICENSE header 8 years ago
txn.go 34bd797e67 *: revert module import paths 5 years ago
txn_test.go 34bd797e67 *: revert module import paths 5 years ago
utils.go 8782bbae65 clientV3: fix behavior of WithPrefix and WithFromKey functions 5 years ago
watch.go 8194aa3f03 Fixed a missing block bug 5 years ago
watch_test.go 34bd797e67 *: revert module import paths 5 years ago

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.