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.

Supported Go Versions

ydb-go-sdk supports all Go versions supported by the official Go Release Policy. That is, the two most recent releases of Go.

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

• connect to YDB

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

• execute SELECT query over Table service 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 SELECT query over Query service 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.

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:

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:

Environment variables

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