github.com/ydb-platform/ydb-go-sdk/v3@v3.89.2/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 `discovery`, `operation`, `table`, `query`, `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 latest two versions of Go (or more, but with no guarantees for extra versions). 24 25 26 ## Versioning Policy 27 28 `ydb-go-sdk` comply to guidelines from [SemVer2.0.0](https://semver.org/) with an several [exceptions](VERSIONING.md). 29 30 ## Installation 31 32 ```sh 33 go get -u github.com/ydb-platform/ydb-go-sdk/v3 34 ``` 35 36 ## Example Usage <a name="example"></a> 37 38 * connect to YDB 39 ```go 40 db, err := ydb.Open(ctx, "grpc://localhost:2136/local") 41 if err != nil { 42 log.Fatal(err) 43 } 44 ``` 45 * execute `SELECT` query with `Query` service client 46 ```go 47 // Do retry operation on errors with best effort 48 err := db.Query().Do( // Do retry operation on errors with best effort 49 ctx, // context manage exiting from Do 50 func(ctx context.Context, s query.Session) (err error) { // retry operation 51 streamResult, err := s.Query(ctx, `SELECT 42 as id, "myStr" as myStr;`) 52 if err != nil { 53 return err // for auto-retry with driver 54 } 55 defer func() { _ = streamResult.Close(ctx) }() // cleanup resources 56 for rs, err := range streamResult.ResultSets(ctx) { 57 if err != nil { 58 return err 59 } 60 for row, err := range rs.Rows(ctx) { 61 if err != nil { 62 return err 63 } 64 type myStruct struct { 65 id uint64 `sql:"id"` 66 str string `sql:"myStr"` 67 } 68 var s myStruct 69 if err = row.ScanStruct(&s); err != nil { 70 return err // generally scan error not retryable, return it for driver check error 71 } 72 } 73 } 74 75 return nil 76 }, 77 query.WithIdempotent(), 78 ) 79 if err != nil { 80 log.Fatal(err) 81 } 82 ``` 83 84 * usage with `database/sql` (see additional docs in [SQL.md](SQL.md) ) 85 ```go 86 import ( 87 "context" 88 "database/sql" 89 "log" 90 91 _ "github.com/ydb-platform/ydb-go-sdk/v3" 92 ) 93 94 ... 95 96 db, err := sql.Open("ydb", "grpc://localhost:2136/local") 97 if err != nil { 98 log.Fatal(err) 99 } 100 defer db.Close() // cleanup resources 101 var ( 102 id int32 103 myStr string 104 ) 105 row := db.QueryRowContext(context.TODO(), `SELECT 42 as id, "my string" as myStr`) 106 if err = row.Scan(&id, &myStr); err != nil { 107 log.Printf("select failed: %v", err) 108 return 109 } 110 log.Printf("id = %d, myStr = \"%s\"", id, myStr) 111 ``` 112 113 114 More examples of usage placed in [examples](./examples) directory. 115 116 ## Credentials <a name="credentials"></a> 117 118 Driver implements several ways for making credentials for `YDB`: 119 - `ydb.WithAnonymousCredentials()` (enabled by default unless otherwise specified) 120 - `ydb.WithAccessTokenCredentials("token")` 121 - `ydb.WithStaticCredentials("user", "password")`, 122 - `ydb.WithOauth2TokenExchangeCredentials()` and `ydb,WithOauth2TokenExchangeCredentialsFile(configFilePath)` 123 - as part of connection string, like as `grpcs://user:password@endpoint/database` 124 125 Another variants of `credentials.Credentials` object provides with external packages: 126 127 | Package | Type | Description | Link of example usage | 128 |------------------------------------------------------------------------------------|-------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 129 | [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) | 130 | [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) | 131 | [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) | 132 133 ## Ecosystem of debug tools over `ydb-go-sdk` <a name="debug"></a> 134 135 Package `ydb-go-sdk` provide debugging over trace events in package `trace`. 136 Next packages provide debug tooling: 137 138 | Package | Type | Description | Link of example usage | 139 |----------------------------------------------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| 140 | [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) | 141 | [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) | 142 | [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) | 143 | [ydb-go-sdk-prometheus](https://github.com/ydb-platform/ydb-go-sdk-prometheus/v2) | metrics | prometheus wrapper over [ydb-go-sdk/v3/metrics](https://github.com/ydb-platform/ydb-go-sdk/tree/master/metrics) | [ydbPrometheus.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-prometheus/blob/master/internal/cmd/bench/main.go#L56) | 144 | [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) | 145 | [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) | 146 147 ## Environment variables <a name="environ"></a> 148 149 `ydb-go-sdk` supports next environment variables which redefines default behavior of driver 150 151 | Name | Type | Default | Description | 152 |----------------------------------|-----------|---------|--------------------------------------------------------------------------------------------------------------------------| 153 | `YDB_SSL_ROOT_CERTIFICATES_FILE` | `string` | | path to certificates file | 154 | `YDB_LOG_SEVERITY_LEVEL` | `string` | `quiet` | severity logging level of internal driver logger. Supported: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `quiet` | 155 | `YDB_LOG_DETAILS` | `string` | `.*` | regexp for lookup internal logger logs | 156 | `GRPC_GO_LOG_VERBOSITY_LEVEL` | `integer` | | set to `99` to see grpc logs | 157 | `GRPC_GO_LOG_SEVERITY_LEVEL` | `string` | | set to `info` to see grpc logs |