• Stars
    star
    139
  • Rank 262,902 (Top 6 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 3 years ago
  • Updated 16 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
C++
3,982
star
2

ydb-python-sdk

YDB Python SDK
Python
87
star
3

ydb-java-dialects

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

ydb-nodejs-sdk

YDB Node.js SDK
TypeScript
60
star
5

nbs

Network Block & File Store
C++
58
star
6

ydb-rs-sdk

Rust
48
star
7

ydb-kubernetes-operator

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

ydb-java-sdk

YDB Java SDK
Java
36
star
9

jaeger-ydb-store

Go
31
star
10

ydb-dotnet-sdk

YDB .NET SDK
C#
28
star
11

ydb-embedded-ui

TypeScript
27
star
12

ydb-php-sdk

PHP
26
star
13

ydb-sqlalchemy

YQL Dialect for SQLAlchemy
Python
21
star
14

ydb-jdbc-driver

YDB JDBC Driver
Java
18
star
15

ydb-api-protos

14
star
16

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
17

ydb-presentations

YDB public talks, slides and recordings
Shell
11
star
18

ydb-cpp-sdk

YDB C++ SDK
C++
10
star
19

tpcc

TPC-C for YDB
Java
9
star
20

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
21

gorm-driver

GORM YDB driver
Go
6
star
22

ydb-ui-components

TypeScript
5
star
23

ydb-go-genproto

Go
5
star
24

terraform-provider-ydb

Go
5
star
25

ydb-go-yc

Go
5
star
26

ydb-php-examples

PHP
4
star
27

ydb-go-sdk-opentracing

Go
4
star
28

ydb-go-sdk-zerolog

Go
4
star
29

ydb-grafana-datasource-plugin

Grafana datasource plugin for YDB
TypeScript
4
star
30

tpcc-postgres

TPC-C for PostgreSQL
Java
4
star
31

ydb-dotnet-examples

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

fq-connector-go

External data source connector for YDB Federated Query
Go
4
star
33

ydb-go-sdk-zap

Go
3
star
34

ydb-go-sql

Go
3
star
35

ydb-go-sdk-prometheus

Go
3
star
36

postgres-compatibility-tests

PLpgSQL
3
star
37

ydb-go-yc-metadata

Go
3
star
38

ydb-r2dbc-driver

YDB R2DBC Driver
Java
3
star
39

ydb-go-sdk-metrics

Deprecated: use ydb-go-sdk/v3/metrics package instead
Go
3
star
40

ydb-ansible

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

ydb-go-persqueue-sdk

YDB Persqueue Golang SDK
Go
2
star
42

ydb-nodejs-genproto

JavaScript
2
star
43

ydb-go-sdk-auth-environ

Go
2
star
44

ydb-go-sdk-otel

OpenTelemetry adapter for ydb-go-sdk
Go
2
star
45

benchhelpers

Scripts and tools to bench YDB and other DBs
Python
2
star
46

ydb-java-examples

Java
2
star
47

ydb-dotnet-yc

Yandex.Cloud libraries for YDB .NET SDK
C#
2
star
48

ydbcp

YDB Control Plane
Go
2
star
49

xorm

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

ydb-importer

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

fluent-bit-ydb

Fluent-Bit go YDB output plugin
Go
1
star
52

ydb-dotnet-genproto

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

slo-tests

TypeScript
1
star
54

json2parquet

Simple streaming json2parquet converter
C++
1
star
55

postgres_vs_distributed

This repository contains config files used in our blog post
Python
1
star
56

ydb-kafka-sink-connector

Java
1
star
57

ydb-terraform

HCL
1
star