yura cf7be488a9 clientv3: concurrency.Mutex.Lock() - preserve invariant 6 years ago
..
concurrency cf7be488a9 clientv3: concurrency.Mutex.Lock() - preserve invariant 6 years ago
integration 081519c323 clientv3: fix keepalive send interval when response queue is full 6 years ago
mirror 16b0c1d1e1 clientv3: fix sync base 8 years ago
naming c20d31adc5 clientv3/naming: support OpOption when adding an endpoint 8 years ago
README.md 195570b621 clientv3: updated doc for metric support 8 years ago
auth.go 9205a242b9 clientv3: do not retry on mutable operations 8 years ago
balancer.go 81f151eed2 clientv3: fix retry logic 8 years ago
balancer_test.go 6d443ba3f9 clienv3: fix balancer test logic 8 years ago
client.go 6538217528 clientv3: respect dial timeout when authenticating 7 years ago
client_test.go 38f79fa565 clientv3: fix gofmt warnings 7 years ago
cluster.go 9205a242b9 clientv3: do not retry on mutable operations 8 years ago
compact_op.go 76e2bf03b8 etcdctl: v3 compact with physical flag 8 years ago
compact_op_test.go 859e336d68 clientv3: configurable physical in compact 8 years ago
compare.go c2fd42b556 etcdserver, clientv3: add "!=" to txn 8 years ago
config.go 084c407a8d clientv3: drop Config.Logger field 8 years ago
config_test.go fd9e07a529 clientv3: update LICENSE header 8 years ago
doc.go e7e29ba249 clientv3: Fix URL to rpc errors 8 years ago
example_auth_test.go bc5d7bbe03 auth, e2e, clientv3: the root role should be granted access to every key 8 years ago
example_cluster_test.go fd9e07a529 clientv3: update LICENSE header 8 years ago
example_kv_test.go 1c25aa6c48 clientv3, ctl3, clientv3/integration: add compact response to compact 8 years ago
example_lease_test.go fd9e07a529 clientv3: update LICENSE header 8 years ago
example_maintenence_test.go fd9e07a529 clientv3: update LICENSE header 8 years ago
example_metrics_test.go a1bfb31219 clientv3: added example for client metrics 8 years ago
example_test.go 084c407a8d clientv3: drop Config.Logger field 8 years ago
example_watch_test.go fd9e07a529 clientv3: update LICENSE header 8 years ago
kv.go 81f151eed2 clientv3: fix retry logic 8 years ago
lease.go 081519c323 clientv3: fix keepalive send interval when response queue is full 6 years ago
logger.go 084c407a8d clientv3: drop Config.Logger field 8 years ago
main_test.go 0b0cbaac09 clientv3: use cheap bcrypt for ExampleAuth and use embedded auth api 8 years ago
maintenance.go d8f0ef0e80 clientv3: use grpc.FailFast(false) for all calls 8 years ago
op.go 9dd75a946f clientv3, ctlv3: document range end requirement 8 years ago
op_test.go ddddecc3ab clientv3: ignore sort-ascend-key option 8 years ago
retry.go d431b64d97 etcdserver, clientv3: handle a case of expired auth token 8 years ago
sort.go fd9e07a529 clientv3: update LICENSE header 8 years ago
txn.go 3552420dfd clientv3: set failfast=false on read-only txns 8 years ago
txn_test.go 984badeb03 testutil, clientv3: wait for panics in txn tests to complete 8 years ago
watch.go 78141fae60 clientv3: set current revision to create rev regardless of CreateNotify 7 years ago
watch_test.go fd9e07a529 clientv3: update LICENSE header 8 years ago

README.md

etcd/clientv3

Godoc

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:

  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 := 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)
	}
}

Metrics

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

Examples

More code examples can be found at GoDoc.