1# etcd/clientv3
2
3[](https://etcd.io/docs)
4[](https://godoc.org/go.etcd.io/etcd/clientv3)
5
6`etcd/clientv3` is the official Go etcd client for v3.
7
8## Install
9
10```bash
11go get go.etcd.io/etcd/client/v3
12```
13
14Warning: As etcd 3.5.0 was not yet released, the command above does not work.
15After first pre-release of 3.5.0 [#12498](https://github.com/etcd-io/etcd/issues/12498),
16etcd can be referenced using:
17```
18go get go.etcd.io/etcd/client/v3@v3.5.0-pre
19```
20
21## Get started
22
23Create client using `clientv3.New`:
24
25```go
26cli, err := clientv3.New(clientv3.Config{
27 Endpoints: []string{"localhost:2379", "localhost:22379", "localhost:32379"},
28 DialTimeout: 5 * time.Second,
29})
30if err != nil {
31 // handle error!
32}
33defer cli.Close()
34```
35
36etcd v3 uses [`gRPC`](https://www.grpc.io) for remote procedure calls. And `clientv3` uses
37[`grpc-go`](https://github.com/grpc/grpc-go) to connect to etcd. Make sure to close the client after using it.
38If the client is not closed, the connection will have leaky goroutines. To specify client request timeout,
39pass `context.WithTimeout` to APIs:
40
41```go
42ctx, cancel := context.WithTimeout(context.Background(), timeout)
43resp, err := cli.Put(ctx, "sample_key", "sample_value")
44cancel()
45if err != nil {
46 // handle error!
47}
48// use the response
49```
50
51For full compatibility, it is recommended to install released versions of clients using go modules.
52
53## Error Handling
54
55etcd client returns 2 types of errors:
56
571. context error: canceled or deadline exceeded.
582. gRPC error: see [api/v3rpc/rpctypes](https://godoc.org/go.etcd.io/etcd/api/v3rpc/rpctypes).
59
60Here is the example code to handle client errors:
61
62```go
63resp, err := cli.Put(ctx, "", "")
64if err != nil {
65 switch err {
66 case context.Canceled:
67 log.Fatalf("ctx is canceled by another routine: %v", err)
68 case context.DeadlineExceeded:
69 log.Fatalf("ctx is attached with a deadline is exceeded: %v", err)
70 case rpctypes.ErrEmptyKey:
71 log.Fatalf("client-side error: %v", err)
72 default:
73 log.Fatalf("bad cluster endpoints, which are not etcd servers: %v", err)
74 }
75}
76```
77
78## Metrics
79
80The 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/main/tests/integration/clientv3/examples/example_metrics_test.go).
81
82## Namespacing
83
84The [namespace](https://godoc.org/go.etcd.io/etcd/client/v3/namespace) package provides `clientv3` interface wrappers to transparently isolate client requests to a user-defined prefix.
85
86## Request size limit
87
88Client 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`.
89
90## Examples
91
92More code [examples](https://github.com/etcd-io/etcd/tree/main/tests/integration/clientv3/examples) can be found at [GoDoc](https://pkg.go.dev/go.etcd.io/etcd/client/v3).
View as plain text