https://github.com/ydb-platform/ydb-go-sdk
Pure Go native and database/sql driver for YDB
https://github.com/ydb-platform/ydb-go-sdk
database-sql golang ydb ydb-go-sdk ydb-platform ydb-sdk
Last synced: 8 months ago
JSON representation
Pure Go native and database/sql driver for YDB
- Host: GitHub
- URL: https://github.com/ydb-platform/ydb-go-sdk
- Owner: ydb-platform
- License: apache-2.0
- Created: 2021-08-03T09:40:19.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-04-10T22:01:40.000Z (8 months ago)
- Last Synced: 2025-04-11T23:15:36.048Z (8 months ago)
- Topics: database-sql, golang, ydb, ydb-go-sdk, ydb-platform, ydb-sdk
- Language: Go
- Homepage: https://ydb.tech
- Size: 22.7 MB
- Stars: 151
- Watchers: 18
- Forks: 92
- Open Issues: 234
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Authors: AUTHORS
Awesome Lists containing this project
- awesome-go-cn - ydb-go-sdk - platform/ydb-go-sdk) [![godoc][D]](https://godoc.org/github.com/ydb-platform/ydb-go-sdk) (数据库驱动程序 / 关系数据库驱动程序)
- awesome-go-plus - ydb-go-sdk - native and database/sql driver YDB (Yandex Database)  (Database Drivers / Relational Database Drivers)
- awesome-go - ydb-go-sdk - native and database/sql driver YDB (Yandex Database) (Database Drivers / Relational Database Drivers)
- fucking-awesome-go - ydb-go-sdk - native and database/sql driver YDB (Yandex Database). (Database Drivers / Relational Database Drivers)
- awesome-go - ydb-go-sdk - native and database/sql driver YDB (Yandex Database) (Database Drivers / Relational Database Drivers)
- awesome-go - ydb-go-sdk - native and database/sql driver YDB (Yandex Database) (Database Drivers / Relational Database Drivers)
- awesome-go - ydb-platform/ydb-go-sdk
- awesome-go-cn - ydb-go-sdk - platform/ydb-go-sdk) [![godoc][D]](https://godoc.org/github.com/ydb-platform/ydb-go-sdk) (数据库驱动程序 / 关系数据库驱动程序)
- awesome-go - ydb-go-sdk - native and database/sql driver YDB (Yandex Database). (Database Drivers / Relational Database Drivers)
- awesome-go-with-stars - ydb-go-sdk - native and database/sql driver YDB (Yandex Database). (Database Drivers / Relational Database Drivers)
- awesome-go - ydb-go-sdk - native and database/sql driver YDB (Yandex Database). (Database Drivers / Relational Database Drivers)
README
# `ydb-go-sdk` - pure Go native and `database/sql` driver for [YDB](https://github.com/ydb-platform/ydb)
[](https://github.com/ydb-platform/ydb/blob/main/LICENSE)
[](https://github.com/ydb-platform/ydb-go-sdk/releases)
[](https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3)
[](https://goreportcard.com/report/github.com/ydb-platform/ydb-go-sdk/v3)
[](https://app.codecov.io/gh/ydb-platform/ydb-go-sdk)
[](https://github.com/ydb-platform/ydb-go-sdk/tree/master/examples)
[](https://t.me/ydb_en)
[](https://ydb.tech)
[](https://github.com/ydb-platform/ydb-go-sdk/blob/master/CONTRIBUTING.md)
Supports `discovery`, `operation`, `table`, `query`, `coordination`, `ratelimiter`, `scheme`, `scripting` and `topic` clients for [YDB](https://ydb.tech).
`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.
`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.
## Supported Go Versions
`ydb-go-sdk` supports all Go versions supported by the official [Go Release Policy](https://go.dev/doc/devel/release#policy).
That is, the latest two versions of Go (or more, but with no guarantees for extra versions).
## Versioning Policy
`ydb-go-sdk` comply to guidelines from [SemVer2.0.0](https://semver.org/) with an several [exceptions](VERSIONING.md).
## Installation
```sh
go get -u github.com/ydb-platform/ydb-go-sdk/v3
```
* connect to YDB
```go
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
log.Fatal(err)
}
```
* execute `SELECT` query with `Query` service client
```go
// Do retry operation on errors with best effort
err := db.Query().Do( // Do retry operation on errors with best effort
ctx, // context manage exiting from Do
func(ctx context.Context, s query.Session) (err error) { // retry operation
streamResult, err := s.Query(ctx, `SELECT 42 as id, "myStr" as myStr;`)
if err != nil {
return err // for auto-retry with driver
}
defer func() { _ = streamResult.Close(ctx) }() // cleanup resources
for rs, err := range streamResult.ResultSets(ctx) {
if err != nil {
return err
}
for row, err := range rs.Rows(ctx) {
if err != nil {
return err
}
type myStruct struct {
Id int32 `sql:"id"`
Str string `sql:"myStr"`
}
var s myStruct
if err = row.ScanStruct(&s); err != nil {
return err // generally scan error not retryable, return it for driver check error
}
}
}
return nil
},
query.WithIdempotent(),
)
if err != nil {
log.Fatal(err)
}
```
* usage with `database/sql` (see additional docs in [SQL.md](SQL.md) )
```go
import (
"context"
"database/sql"
"log"
_ "github.com/ydb-platform/ydb-go-sdk/v3"
)
...
db, err := sql.Open("ydb", "grpc://localhost:2136/local")
if err != nil {
log.Fatal(err)
}
defer db.Close() // cleanup resources
var (
id int32
myStr string
)
row := db.QueryRowContext(context.TODO(), `SELECT 42 as id, "my string" as myStr`)
if err = row.Scan(&id, &myStr); err != nil {
log.Printf("select failed: %v", err)
return
}
log.Printf("id = %d, myStr = \"%s\"", id, myStr)
```
More examples of usage placed in [examples](./examples) directory.
Driver implements several ways for making credentials for `YDB`:
- `ydb.WithAnonymousCredentials()` (enabled by default unless otherwise specified)
- `ydb.WithAccessTokenCredentials("token")`
- `ydb.WithStaticCredentials("user", "password")`,
- `ydb.WithOauth2TokenExchangeCredentials()` and `ydb,WithOauth2TokenExchangeCredentialsFile(configFilePath)`
- as part of connection string, like as `grpcs://user:password@endpoint/database`
Another variants of `credentials.Credentials` object provides with external packages:
| Package | Type | Description | Link of example usage |
|------------------------------------------------------------------------------------|-------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [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) |
| [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) |
| [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) |
## Ecosystem of debug tools over `ydb-go-sdk`
Package `ydb-go-sdk` provide debugging over trace events in package `trace`.
Next packages provide debug tooling:
| Package | Type | Description | Link of example usage |
|----------------------------------------------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| [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) |
| [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) |
| [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) |
| [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) |
| [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) |
| [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) |
`ydb-go-sdk` supports next environment variables which redefines default behavior of driver
| Name | Type | Default | Description |
|----------------------------------|-----------|---------|--------------------------------------------------------------------------------------------------------------------------|
| `YDB_SSL_ROOT_CERTIFICATES_FILE` | `string` | | path to certificates file |
| `YDB_LOG_SEVERITY_LEVEL` | `string` | `quiet` | severity logging level of internal driver logger. Supported: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `quiet` |
| `YDB_LOG_DETAILS` | `string` | `.*` | regexp for lookup internal logger logs |
| `GRPC_GO_LOG_VERBOSITY_LEVEL` | `integer` | | set to `99` to see grpc logs |
| `GRPC_GO_LOG_SEVERITY_LEVEL` | `string` | | set to `info` to see grpc logs |