• Stars
    star
    126
  • Rank 274,618 (Top 6 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 2 years ago
  • Updated 5 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Pure Go native and database/sql driver for YDB

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 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:

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

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

More Repositories

1

ydb

YDB is an open source Distributed SQL Database that combines high availability and scalability with strong consistency and ACID transactions
3,415
star
2

ydb-python-sdk

YDB Python SDK
Python
71
star
3

ydb-java-dialects

The official YDB Dialects for Java ORM frameworks and migration tools.
Java
66
star
4

ydb-nodejs-sdk

YDB Node.js SDK
TypeScript
56
star
5

nbs

Network Block Store
C++
46
star
6

ydb-rs-sdk

Rust
45
star
7

ydb-kubernetes-operator

YDB Operator allows you to deploy your own YDB cluster in Kubernetes
Go
40
star
8

jaeger-ydb-store

Go
31
star
9

ydb-java-sdk

YDB Java SDK
Java
29
star
10

ydb-php-sdk

PHP
25
star
11

ydb-dotnet-sdk

YDB .NET SDK
C#
21
star
12

ydb-embedded-ui

TypeScript
20
star
13

ydb-jdbc-driver

YDB JDBC Driver
Java
13
star
14

ydb-sqlalchemy

YQL Dialect for SQLAlchemy
Python
13
star
15

ydb-go-examples

Deprecated. See [examples in ydb-go-sdk repository](https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples)
Go
12
star
16

ydb-api-protos

11
star
17

ydb-presentations

YDB public talks, slides and recordings
Shell
9
star
18

yoj-project

YDB ORM for Java (YOJ) is a lightweight ORM for immutable entities. It has native support for YDB and is battle-tested.
Java
8
star
19

tpcc

TPC-C for YDB
Java
7
star
20

ydb-cpp-sdk

YDB C++ SDK
C++
6
star
21

ydb-ui-components

TypeScript
5
star
22

terraform-provider-ydb

Go
5
star
23

ydb-go-yc

Go
5
star
24

gorm-driver

GORM YDB driver
Go
5
star
25

ydb-php-examples

PHP
4
star
26

ydb-grafana-datasource-plugin

Grafana datasource plugin for YDB
TypeScript
4
star
27

ydb-go-sdk-zerolog

Go
4
star
28

ydb-dotnet-examples

Code examples for YDB .NET SDK
C#
4
star
29

ydb-go-sdk-opentracing

Go
4
star
30

ydb-go-genproto

Go
3
star
31

ydb-go-sdk-metrics

Go
3
star
32

ydb-go-sdk-zap

Go
3
star
33

ydb-go-sql

Go
3
star
34

ydb-go-sdk-prometheus

Go
3
star
35

postgres-compatibility-tests

Python
3
star
36

ydb-go-yc-metadata

Go
3
star
37

fq-connector-go

External data source connector for YDB Federated Query
Go
3
star
38

ydb-ansible

Ansible playbooks for YDB cluster deployment and maintenance
Shell
2
star
39

ydb-go-persqueue-sdk

YDB Persqueue Golang SDK
Go
2
star
40

ydb-nodejs-genproto

JavaScript
2
star
41

ydb-go-sdk-auth-environ

Go
2
star
42

ydb-java-examples

Java
2
star
43

ydb-go-sdk-otel

OpenTelemetry adapter for ydb-go-sdk
Go
1
star
44

ydb-importer

A simple tool to import data from JDBC data sources to YDB
Java
1
star
45

fluent-bit-ydb

Fluent-Bit go YDB output plugin
Go
1
star
46

xorm

Fork of https://gitea.com/xorm/xorm.git
Go
1
star
47

ydb-dotnet-genproto

.NET codegen for YDB API protos.
C#
1
star
48

ydb-dotnet-yc

Yandex.Cloud libraries for YDB .NET SDK
C#
1
star
49

slo-tests

JavaScript
1
star
50

ydb-r2dbc-driver

YDB R2DBC Driver
Java
1
star
51

json2parquet

Simple streaming json2parquet converter
C++
1
star