Awesome
ydb-go-sdk
- pure Go native and database/sql
driver for YDB
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>
- connect to YDB
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
log.Fatal(err)
}
- execute
SELECT
query withQuery
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
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)
}
- 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 <a name="credentials"></a>
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()
andydb,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 | 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
<a name="debug"></a>
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 |
Environment variables <a name="environ"></a>
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 |