README.md
1# etcd/clientv3
2
3[](https://etcd.readthedocs.io/en/latest/?badge=latest)
4[](https://godoc.org/go.etcd.io/etcd/clientv3)
5
6`etcd/clientv3` is the official Go etcd client for v3.
7
8See https://etcd.readthedocs.io/en/latest for latest client architecture.
9
10## Install
11
12```bash
13go get go.etcd.io/etcd/clientv3
14```
15
16## Get started
17
18Create client using `clientv3.New`:
19
20```go
21cli, err := clientv3.New(clientv3.Config{
22 Endpoints: []string{"localhost:2379", "localhost:22379", "localhost:32379"},
23 DialTimeout: 5 * time.Second,
24})
25if err != nil {
26 // handle error!
27}
28defer cli.Close()
29```
30
31etcd v3 uses [`gRPC`](https://www.grpc.io) for remote procedure calls. And `clientv3` uses
32[`grpc-go`](https://github.com/grpc/grpc-go) to connect to etcd. Make sure to close the client after using it.
33If the client is not closed, the connection will have leaky goroutines. To specify client request timeout,
34pass `context.WithTimeout` to APIs:
35
36```go
37ctx, cancel := context.WithTimeout(context.Background(), timeout)
38resp, err := cli.Put(ctx, "sample_key", "sample_value")
39cancel()
40if err != nil {
41 // handle error!
42}
43// use the response
44```
45
46For full compatibility, it is recommended to vendor builds using etcd's vendored packages, using tools like `golang/dep`, as in [vendor directories](https://golang.org/cmd/go/#hdr-Vendor_Directories).
47
48## Error Handling
49
50etcd client returns 2 types of errors:
51
521. context error: canceled or deadline exceeded.
532. gRPC error: see [api/v3rpc/rpctypes](https://godoc.org/go.etcd.io/etcd/etcdserver/api/v3rpc/rpctypes).
54
55Here is the example code to handle client errors:
56
57```go
58resp, err := cli.Put(ctx, "", "")
59if err != nil {
60 switch err {
61 case context.Canceled:
62 log.Fatalf("ctx is canceled by another routine: %v", err)
63 case context.DeadlineExceeded:
64 log.Fatalf("ctx is attached with a deadline is exceeded: %v", err)
65 case rpctypes.ErrEmptyKey:
66 log.Fatalf("client-side error: %v", err)
67 default:
68 log.Fatalf("bad cluster endpoints, which are not etcd servers: %v", err)
69 }
70}
71```
72
73## Metrics
74
75The etcd client optionally exposes RPC metrics through [go-grpc-prometheus](https://github.com/grpc-ecosystem/go-grpc-prometheus). See the [examples](https://github.com/etcd-io/etcd/blob/master/clientv3/example_metrics_test.go).
76
77## Namespacing
78
79The [namespace](https://godoc.org/go.etcd.io/etcd/clientv3/namespace) package provides `clientv3` interface wrappers to transparently isolate client requests to a user-defined prefix.
80
81## Request size limit
82
83Client 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`.
84
85## Examples
86
87More code examples can be found at [GoDoc](https://godoc.org/go.etcd.io/etcd/clientv3).
88
){kind=link}