Home

Awesome

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

License Release PkgGoDev tests lint Go Report Card codecov Code lines View examples Telegram WebSite PRs Welcome

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

Supported Go Versions

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).

Versioning Policy

ydb-go-sdk comply to guidelines from SemVer2.0.0 with an several exceptions.

Installation

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

Example Usage <a name="example"></a>

db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
    log.Fatal(err)
}
// 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  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 nil
   },
   query.WithIdempotent(),
)
if err != nil {
   log.Fatal(err)
}
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.

Credentials <a name="credentials"></a>

Driver implements several ways for making credentials for YDB:

Another variants of credentials.Credentials object provides with external packages:

PackageTypeDescriptionLink of example usage
ydb-go-yccredentialscredentials provider for Yandex.Cloudyc.WithServiceAccountKeyFileCredentials yc.WithInternalCA yc.WithMetadataCredentials
ydb-go-yc-metadatacredentialsmetadata credentials provider for Yandex.Cloudyc.WithInternalCA yc.WithCredentials
ydb-go-sdk-auth-environcredentialscreate credentials from environydbEnviron.WithEnvironCredentials

Ecosystem of debug tools over ydb-go-sdk <a name="debug"></a>

Package ydb-go-sdk provide debugging over trace events in package trace. Next packages provide debug tooling:

PackageTypeDescriptionLink of example usage
ydb-go-sdk-zaplogginglogging ydb-go-sdk events with zap packageydbZap.WithTraces
ydb-go-sdk-zerologlogginglogging ydb-go-sdk events with zerolog packageydbZerolog.WithTraces
ydb-go-sdk-logruslogginglogging ydb-go-sdk events with logrus packageydbLogrus.WithTraces
ydb-go-sdk-prometheusmetricsprometheus wrapper over ydb-go-sdk/v3/metricsydbPrometheus.WithTraces
ydb-go-sdk-opentracingtracingOpenTracing plugin for trace internal ydb-go-sdk callsydbOpentracing.WithTraces
ydb-go-sdk-oteltracingOpenTelemetry plugin for trace internal ydb-go-sdk callsydbOtel.WithTraces

Environment variables <a name="environ"></a>

ydb-go-sdk supports next environment variables which redefines default behavior of driver

NameTypeDefaultDescription
YDB_SSL_ROOT_CERTIFICATES_FILEstringpath to certificates file
YDB_LOG_SEVERITY_LEVELstringquietseverity logging level of internal driver logger. Supported: trace, debug, info, warn, error, fatal, quiet
YDB_LOG_DETAILSstring.*regexp for lookup internal logger logs
GRPC_GO_LOG_VERBOSITY_LEVELintegerset to 99 to see grpc logs
GRPC_GO_LOG_SEVERITY_LEVELstringset to info to see grpc logs