github.com/ydb-platform/ydb-go-sdk/v3@v3.57.0/README.md (about) 1 # `ydb-go-sdk` - pure Go native and `database/sql` driver for [YDB](https://github.com/ydb-platform/ydb) 2 3 [](https://github.com/ydb-platform/ydb/blob/main/LICENSE) 4 [](https://github.com/ydb-platform/ydb-go-sdk/releases) 5 [](https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3) 6  7  8 [](https://goreportcard.com/report/github.com/ydb-platform/ydb-go-sdk/v3) 9 [](https://app.codecov.io/gh/ydb-platform/ydb-go-sdk) 10  11 [](https://github.com/ydb-platform/ydb-go-sdk/tree/master/examples) 12 [](https://t.me/ydb_en) 13 [](https://ydb.tech) 14 [](https://github.com/ydb-platform/ydb-go-sdk/blob/master/CONTRIBUTING.md) 15 16 Supports `table`, `discovery`, `coordination`, `ratelimiter`, `scheme`, `scripting` and `topic` clients for [YDB](https://ydb.tech). 17 `YDB` is an open-source Distributed SQL Database that combines high availability and scalability with strict consistency and [ACID](https://en.wikipedia.org/wiki/ACID) transactions. 18 `YDB` was created primarily for [OLTP](https://en.wikipedia.org/wiki/Online_transaction_processing) workloads and supports some [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) scenarious. 19 20 ## Supported Go Versions 21 22 `ydb-go-sdk` supports all Go versions supported by the official [Go Release Policy](https://go.dev/doc/devel/release#policy). 23 That is, the two most recent releases of Go. 24 25 ## Installation 26 27 ```sh 28 go get -u github.com/ydb-platform/ydb-go-sdk/v3 29 ``` 30 31 ## Example Usage <a name="example"></a> 32 33 * connect to YDB 34 ```golang 35 db, err := ydb.Open(ctx, "grpc://localhost:2136/local") 36 if err != nil { 37 log.Fatal(err) 38 } 39 ``` 40 * execute `SELECT` query 41 ```golang 42 const query = `SELECT 42 as id, "myStr" as myStr;` 43 44 // Do retry operation on errors with best effort 45 queryErr := db.Table().Do(ctx, func(ctx context.Context, s table.Session) (err error) { 46 _, res, err := s.Execute(ctx, table.DefaultTxControl(), query, nil) 47 if err != nil { 48 return err 49 } 50 defer res.Close() 51 if err = res.NextResultSetErr(ctx); err != nil { 52 return err 53 } 54 for res.NextRow() { 55 var id int32 56 var myStr string 57 err = res.ScanNamed(named.Required("id", &id),named.OptionalWithDefault("myStr", &myStr)) 58 if err != nil { 59 log.Fatal(err) 60 } 61 log.Printf("id=%v, myStr='%s'\n", id, myStr) 62 } 63 return res.Err() // for driver retry if not nil 64 }) 65 if queryErr != nil { 66 log.Fatal(queryErr) 67 } 68 ``` 69 * usage with `database/sql` (see additional docs in [SQL.md](SQL.md) ) 70 ```golang 71 import ( 72 "context" 73 "database/sql" 74 "log" 75 76 _ "github.com/ydb-platform/ydb-go-sdk/v3" 77 ) 78 79 ... 80 81 db, err := sql.Open("ydb", "grpc://localhost:2136/local") 82 if err != nil { 83 log.Fatal(err) 84 } 85 defer db.Close() // cleanup resources 86 var ( 87 id int32 88 myStr string 89 ) 90 row := db.QueryRowContext(context.TODO(), `SELECT 42 as id, "my string" as myStr`) 91 if err = row.Scan(&id, &myStr); err != nil { 92 log.Printf("select failed: %v", err) 93 return 94 } 95 log.Printf("id = %d, myStr = \"%s\"", id, myStr) 96 ``` 97 98 99 More examples of usage placed in [examples](https://github.com/ydb-platform/ydb-go-examples) repository. 100 101 ## Credentials <a name="credentials"></a> 102 103 Driver implements several ways for making credentials for `YDB`: 104 - `ydb.WithAnonymousCredentials()` (enabled by default unless otherwise specified) 105 - `ydb.WithAccessTokenCredentials("token")` 106 - `ydb.WithStaticCredentials("user", "password")`, 107 - as part of connection string, like as `grpcs://user:password@endpoint/database` 108 109 Another variants of `credentials.Credentials` object provides with external packages: 110 111 | Package | Type | Description | Link of example usage | 112 |------------------------------------------------------------------------------------|-------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 113 | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc) | credentials | credentials provider for Yandex.Cloud | [yc.WithServiceAccountKeyFileCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22) [yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22) [yc.WithMetadataCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L24) | 114 | [ydb-go-yc-metadata](https://github.com/ydb-platform/ydb-go-yc-metadata) | credentials | metadata credentials provider for Yandex.Cloud | [yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L23) [yc.WithCredentials](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L17) | 115 | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ) | credentials | create credentials from environ | [ydbEnviron.WithEnvironCredentials](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/env.go#L11) | 116 117 ## Ecosystem of debug tools over `ydb-go-sdk` <a name="debug"></a> 118 119 Package `ydb-go-sdk` provide debugging over trace events in package `trace`. 120 Next packages provide debug tooling: 121 122 | Package | Type | Description | Link of example usage | 123 |----------------------------------------------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| 124 | [ydb-go-sdk-zap](https://github.com/ydb-platform/ydb-go-sdk-zap) | logging | logging ydb-go-sdk events with `zap` package | [ydbZap.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zap/blob/master/internal/cmd/bench/main.go#L64) | 125 | [ydb-go-sdk-zerolog](https://github.com/ydb-platform/ydb-go-sdk-zerolog) | logging | logging ydb-go-sdk events with `zerolog` package | [ydbZerolog.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zerolog/blob/master/internal/cmd/bench/main.go#L47) | 126 | [ydb-go-sdk-logrus](https://github.com/ydb-platform/ydb-go-sdk-logrus) | logging | logging ydb-go-sdk events with `logrus` package | [ydbLogrus.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-logrus/blob/master/internal/cmd/bench/main.go#L48) | 127 | [ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | metrics | common metrics of ydb-go-sdk. Package declare interfaces such as `Registry`, `GaugeVec` and `Gauge` and use it for traces | | 128 | [ydb-go-sdk-prometheus](https://github.com/ydb-platform/ydb-go-sdk-prometheus) | metrics | prometheus wrapper over [ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | [ydbPrometheus.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-prometheus/blob/master/internal/cmd/bench/main.go#L56) | 129 | [ydb-go-sdk-opentracing](https://github.com/ydb-platform/ydb-go-sdk-opentracing) | tracing | OpenTracing plugin for trace internal ydb-go-sdk calls | [ydbOpentracing.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-opentracing/blob/master/internal/cmd/bench/main.go#L86) | 130 | [ydb-go-sdk-otel](https://github.com/ydb-platform/ydb-go-sdk-otel) | tracing | OpenTelemetry plugin for trace internal ydb-go-sdk calls | [ydbOtel.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-otel/blob/master/internal/cmd/bench/main.go#L98) | 131 132 ## Environment variables <a name="environ"></a> 133 134 `ydb-go-sdk` supports next environment variables which redefines default behavior of driver 135 136 | Name | Type | Default | Description | 137 |----------------------------------|-----------|---------|--------------------------------------------------------------------------------------------------------------------------| 138 | `YDB_SSL_ROOT_CERTIFICATES_FILE` | `string` | | path to certificates file | 139 | `YDB_LOG_SEVERITY_LEVEL` | `string` | `quiet` | severity logging level of internal driver logger. Supported: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `quiet` | 140 | `YDB_LOG_DETAILS` | `string` | `.*` | regexp for lookup internal logger logs | 141 | `GRPC_GO_LOG_VERBOSITY_LEVEL` | `integer` | | set to `99` to see grpc logs | 142 | `GRPC_GO_LOG_SEVERITY_LEVEL` | `string` | | set to `info` to see grpc logs |