ydb-go-sdk - pure Go native and database/sql driver for YDB
Supports table, query, discovery, coordination, ratelimiter, scheme, scripting and topic clients for YDB.
YDB is an open-source Distributed SQL Database that combines high availability and scalability with strict consistency and ACID transactions.
YDB was created primarily for OLTP workloads and supports some OLAP scenarious.
ydb-go-sdk supports all Go versions supported by the official Go Release Policy.
That is, the latest two versions of Go (or more, but with no guarantees for extra versions).
ydb-go-sdk comply to guidelines from SemVer2.0.0 with an several exceptions.
go get -u github.com/ydb-platform/ydb-go-sdk/v3- connect to YDB
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
log.Fatal(err)
}- execute
SELECTquery overTableservice client
// Do retry operation on errors with best effort
err := db.Table().Do(ctx, func(ctx context.Context, s table.Session) (err error) {
_, res, err := s.Execute(ctx, table.DefaultTxControl(),
`SELECT 42 as id, "myStr" as myStr;`,
nil, // empty parameters
)
if err != nil {
return err
}
defer res.Close()
if err = res.NextResultSetErr(ctx); err != nil {
return err
}
for res.NextRow() {
var id int32
var myStr string
err = res.ScanNamed(named.Required("id", &id),named.OptionalWithDefault("myStr", &myStr))
if err != nil {
log.Fatal(err)
}
log.Printf("id=%v, myStr='%s'\n", id, myStr)
}
return res.Err() // for driver retry if not nil
})
if err != nil {
log.Fatal(err)
}- execute
SELECTquery overQueryservice client
// 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
_, res, err := s.Execute(ctx, `SELECT 42 as id, "myStr" as myStr;`))
if err != nil {
return err // for auto-retry with driver
}
defer func() { _ = res.Close(ctx) }() // cleanup resources
for { // iterate over result sets
rs, err := res.NextResultSet(ctx)
if err != nil {
if errors.Is(err, io.EOF) {
break
}
return err
}
for { // iterate over rows
row, err := rs.NextRow(ctx)
if err != nil {
if errors.Is(err, io.EOF) {
break
}
return err
}
type myStruct struct {
id uint64 `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 res.Err() // return finally result error for auto-retry with driver
},
query.WithIdempotent(),
)
if err != nil {
log.Fatal(err)
}- usage with
database/sql(see additional docs in SQL.md )
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 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"),- 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 | credentials | credentials provider for Yandex.Cloud | yc.WithServiceAccountKeyFileCredentials yc.WithInternalCA yc.WithMetadataCredentials |
| ydb-go-yc-metadata | credentials | metadata credentials provider for Yandex.Cloud | yc.WithInternalCA yc.WithCredentials |
| ydb-go-sdk-auth-environ | credentials | create credentials from environ | ydbEnviron.WithEnvironCredentials |
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 | logging | logging ydb-go-sdk events with zap package |
ydbZap.WithTraces |
| ydb-go-sdk-zerolog | logging | logging ydb-go-sdk events with zerolog package |
ydbZerolog.WithTraces |
| ydb-go-sdk-logrus | logging | logging ydb-go-sdk events with logrus package |
ydbLogrus.WithTraces |
| ydb-go-sdk-prometheus | metrics | prometheus wrapper over ydb-go-sdk/v3/metrics | ydbPrometheus.WithTraces |
| ydb-go-sdk-opentracing | tracing | OpenTracing plugin for trace internal ydb-go-sdk calls | ydbOpentracing.WithTraces |
| ydb-go-sdk-otel | tracing | OpenTelemetry plugin for trace internal ydb-go-sdk calls | ydbOtel.WithTraces |
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 |
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent