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

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.