2016-02-23 00:39:34 +03:00
# etcd/clientv3
2018-06-18 23:51:20 +03:00
[![Docs ](https://readthedocs.org/projects/etcd/badge/?version=latest&style=flat-square )](https://etcd.readthedocs.io/en/latest/?badge=latest)
2018-08-31 02:26:12 +03:00
[![Godoc ](https://img.shields.io/badge/go-documentation-blue.svg?style=flat-square )](https://godoc.org/go.etcd.io/etcd/clientv3)
2016-02-23 00:39:34 +03:00
`etcd/clientv3` is the official Go etcd client for v3.
2018-06-18 23:51:20 +03:00
See https://etcd.readthedocs.io/en/latest for latest client architecture.
2016-02-23 00:39:34 +03:00
## Install
```bash
2018-08-31 02:26:12 +03:00
go get go.etcd.io/etcd/clientv3
2016-02-23 00:39:34 +03:00
```
## Get started
Create client using `clientv3.New` :
```go
cli, err := clientv3.New(clientv3.Config{
2016-03-22 00:21:09 +03:00
Endpoints: []string{"localhost:2379", "localhost:22379", "localhost:32379"},
2016-02-23 00:39:34 +03:00
DialTimeout: 5 * time.Second,
})
if err != nil {
// handle error!
}
defer cli.Close()
```
etcd v3 uses [`gRPC` ](http://www.grpc.io ) for remote procedure calls. And `clientv3` uses
2018-01-18 23:29:22 +03:00
[`grpc-go` ](https://github.com/grpc/grpc-go ) to connect to etcd. Make sure to close the client after using it.
2016-02-23 03:39:05 +03:00
If the client is not closed, the connection will have leaky goroutines. To specify client request timeout,
2016-02-23 00:39:34 +03:00
pass `context.WithTimeout` to APIs:
```go
ctx, cancel := context.WithTimeout(context.Background(), timeout)
2017-02-17 05:54:05 +03:00
resp, err := cli.Put(ctx, "sample_key", "sample_value")
2016-02-23 00:39:34 +03:00
cancel()
if err != nil {
// handle error!
}
// use the response
```
2018-01-15 06:46:20 +03:00
For 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 ).
2016-03-30 19:33:13 +03:00
2016-02-23 00:39:34 +03:00
## Error Handling
2016-03-01 02:41:52 +03:00
etcd client returns 2 types of errors:
1. context error: canceled or deadline exceeded.
2018-08-31 02:26:12 +03:00
2. gRPC error: see [api/v3rpc/rpctypes ](https://godoc.org/go.etcd.io/etcd/etcdserver/api/v3rpc/rpctypes ).
2016-03-01 02:41:52 +03:00
Here is the example code to handle client errors:
```go
2017-02-17 05:54:05 +03:00
resp, err := cli.Put(ctx, "", "")
2016-03-01 02:41:52 +03:00
if err != nil {
2016-04-29 23:26:28 +03:00
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)
2016-03-01 02:41:52 +03:00
}
}
```
2016-02-23 00:39:34 +03:00
2016-11-02 23:57:27 +03:00
## Metrics
2018-08-30 00:28:36 +03:00
The 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 ).
2016-11-02 23:57:27 +03:00
2017-03-21 22:15:07 +03:00
## Namespacing
2018-08-31 02:26:12 +03:00
The [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.
2017-03-21 22:15:07 +03:00
2018-01-18 23:29:22 +03:00
## 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` .
2016-02-23 00:39:34 +03:00
## Examples
2018-08-31 02:26:12 +03:00
More code examples can be found at [GoDoc ](https://godoc.org/go.etcd.io/etcd/clientv3 ).