README.md

ydb-go-sdk - pure Go native and database/sql driver for YDB

Supports table, 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.

Installation

go get -u github.com/ydb-platform/ydb-go-sdk/v3

Example Usage

• connect to YDB

db, err := ydb.Open(ctx, "grpcs://localhost:2135/local")
if err != nil {
    log.Fatal(err)
}

• execute SELECT query

const query = `SELECT 42 as id, "myStr" as myStr;`

// Do retry operation on errors with best effort
queryErr := db.Table().Do(ctx, func(ctx context.Context, s table.Session) (err error) {
   _, res, err := s.Execute(ctx, table.DefaultTxControl(), query, nil)
   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 queryErr != nil {
   log.Fatal(queryErr)
}

• 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", "grpcs://localhost:2135/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 repository.

Credentials

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

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	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-metrics	metrics	common metrics of ydb-go-sdk. Package declare interfaces such as Registry, GaugeVec and Gauge and use it for traces
ydb-go-sdk-prometheus	metrics	prometheus wrapper over ydb-go-sdk-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

Environment variables

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