ydb

package module
v3.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 9, 2021 License: Apache-2.0 Imports: 35 Imported by: 86

README

ydb

PkgGoDev GoDoc tests lint Go Report Card codecov

YDB API client written in Go.

godoc

Table of contents

  1. Overview
  2. About semantic versioning
  3. Prerequisites
  4. Installation
  5. Usage
  6. Credentials
  7. Environment variables
  8. Ecosystem of debug tools
  9. Examples

Overview

Currently package ydb provides scheme and table API client implementations for YDB.

About semantic versioning

We follow the SemVer 2.0.0. In particular, we provide backward compatibility in the MAJOR releases. New features without loss of backward compatibility appear on the MINOR release. In the minor version, the patch number starts from 0. Bug fixes and internal changes are released with the third digit (PATCH) in the version.

There are, however, some changes with the loss of backward compatibility that we consider to be MINOR:

  • extension or modification of internal ydb-go-sdk interfaces. We understand that this will break the compatibility of custom implementations of the ydb-go-sdk internal interfaces. But we believe that the internal interfaces of ydb-go-sdk are implemented well enough that they do not require custom implementation. We are working to ensure that all internal interfaces have limited access only inside ydb-go-sdk.
  • major changes to (including removal of) the public interfaces and types that have been previously exported by ydb-go-sdk. We understand that these changes will break the backward compatibility of early adopters of these interfaces. However, these changes are generally coordinated with early adopters and have the concise interfacing with ydb-go-sdk as a goal.

Internal interfaces outside from internal directory are marked with comment such as

// Warning: only for internal usage inside ydb-go-sdk

We publish the planned breaking MAJOR changes:

  • via the comment Deprecated in the code indicating what should be used instead
  • through the file NEXT_MAJOR_RELEASE.md

Prerequisites

Requires Go 1.13 or later.

Installation 

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

Usage

The straightforward example of querying data may look similar to this:

   ctx := context.Background()

   // connect package helps to connect to database, returns connection object which
   // provide necessary clients such as table.Client, scheme.Client, etc.
   db, err := ydb.New(
      ctx,
      ydb.WithConnectionString(os.Getenv("YDB_CONNECTION_STRING")),
      ydb.WithDialTimeout(3 * time.Second),
      ydb.WithCertificatesFromFile("~/.ydb/CA.pem"),
      ydb.WithSessionPoolIdleThreshold(time.Second * 5),
      ydb.WithSessionPoolKeepAliveMinSize(-1),
      ydb.WithDiscoveryInterval(5 * time.Second),
      ydb.WithAccessTokenCredentials(os.GetEnv("YDB_ACCESS_TOKEN_CREDENTIALS")),
   )
   if err != nil {
      // handle error
   }
   defer func() { _ = db.Close(ctx) }()

   // Prepare transaction control for upcoming query execution.
   // NOTE: result of TxControl() may be reused.
   txc := table.TxControl(
      table.BeginTx(table.WithSerializableReadWrite()),
      table.CommitTx(),
   )

   var res resultset.Result

   // Do() provide the best effort for executing operation
   // Do implements internal busy loop until one of the following conditions occurs:
   // - deadline was cancelled or deadlined
   // - operation returned nil as error
   // Note that in case of prepared statements call to Prepare() must be made
   // inside the function body.
   err := db.Table().Do(
      ctx, 
      func(ctx context.Context, s table.Session) (err error) {
         // Execute text query without preparation and with given "autocommit"
         // transaction control. That is, transaction will be committed without
         // additional calls. Notice the "_" unused variable – it stands for created
         // transaction during execution, but as said above, transaction is committed
         // for us and `ydb-go-sdk` do not want to do anything with it.
         _, res, err := s.Execute(ctx, txc,
            `--!syntax_v1
             DECLARE $mystr AS Utf8?;
             SELECT 42 as id, $mystr as mystr
             `,
            table.NewQueryParameters(
               table.ValueParam("$mystr", types.OptionalValue(types.UTF8Value("test"))),
            ),
         )
         return err
      },
   )
   if err != nil {
       return err // handle error
   }
   defer func() {
      _ = res.Close()
   }()
   // Scan for received values within the result set(s).
   // res.Err() reports the reason of last unsuccessful one.
   var (
       id    int32
       myStr *string //optional value
   )
   for res.NextResultSet(ctx, "id", "mystr") {
       for res.NextRow() {
           // Suppose our "users" table has two rows: id and age.
           // Thus, current row will contain two appropriate items with
           // exactly the same order.
           err := res.Scan(&id, &myStr)
   
           // Error handling.
           if err != nil {
               return err
           }
           // do something with data
           fmt.Printf("got id %v, got mystr: %v\n", id, *myStr)
       }
   }
   if res.Err() != nil {
       return res.Err() // handle error
   }

YDB sessions may become staled and appropriate error will be returned. To reduce boilerplate overhead for such cases ydb-go-sdk provides generic retry logic

Credentials

There are different variants to get ydb.Credentials object to get authorized. Spatial cases of credentials for yandex-cloud provides with package ydb-go-yc Package ydb-go-sdk-auth-environ provide different credentials depending on the environment variables. Usage examples can be found here.

Environment variables

Name Type Default Description
YDB_SSL_ROOT_CERTIFICATES_FILE string path to certificates file
YDB_LOG_SEVERITY_LEVEL string quiet severity logging level. Supported: trace, debug, info, warn, error, fatal, quiet
YDB_LOG_NO_COLOR bool false set any non empty value to disable colouring 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

Ecosystem of debug tools over ydb-go-sdk

Package ydb-go-sdk provide debugging over trace events in package trace. Now supports driver events in trace.Driver struct and table-service events in trace.Table struct. 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 trace.Driver trace.Table
ydb-go-sdk-zerolog logging logging ydb-go-sdk events with zerolog package trace.Driver trace.Table
ydb-go-sdk-metrics metrics common metrics of ydb-go-sdk. Package declare interfaces such as Registry, GaugeVec and Gauge and use it for create trace.Driver and trace.Table traces
ydb-go-sdk-prometheus metrics metrics of ydb-go-sdk. Package use ydb-go-sdk-metrics package and prometheus types for create trace.Driver and trace.Table traces trace.Driver trace.Table
ydb-go-sdk-opentracing tracing WIP

Examples

More examples are listed in examples repository.

Documentation

Index

Constants

View Source 
const Version = meta.Version

Version alias for except cycle import

Variables

This section is empty.

Functions

func IsOperationError 

func IsOperationError(err error) bool

func IsStatusAlreadyExistsError 

func IsStatusAlreadyExistsError(err error) bool

func IsStatusNotFoundError 

func IsStatusNotFoundError(err error) bool

func IsStatusSchemeError 

func IsStatusSchemeError(err error) bool

func IsTimeoutError 

func IsTimeoutError(err error) bool

func IsTransportError 

func IsTransportError(err error) bool

func IsTransportErrorCancelled added in v3.4.3 

func IsTransportErrorCancelled(err error) bool

func IsYdbError added in v3.4.2 

func IsYdbError(err error) bool

func IterateByIssues 

func IterateByIssues(err error, it func(message string, code uint32, severity uint32))

func WithMinLevel added in v3.3.0 

func WithMinLevel(minLevel logger.Level) logger.Option

func WithNamespace added in v3.3.0 

func WithNamespace(namespace string) logger.Option

func WithNoColor added in v3.3.0 

func WithNoColor(b bool) logger.Option

Types

type ConnectParams 

type ConnectParams interface {
	Endpoint() string
	Database() string
	Secure() bool
	Token() string
}

func ConnectionString 

func ConnectionString(uri string) (ConnectParams, error)

func EndpointDatabase 

func EndpointDatabase(endpoint string, database string, secure bool) ConnectParams

func MustConnectionString 

func MustConnectionString(uri string) ConnectParams

type Connection 

type Connection interface {
	DB

	Table() table.Client
	Scheme() scheme.Client
	Coordination() coordination.Client
	RateLimiter() ratelimiter.Client
	Discovery() discovery.Client
}

func New 

func New(ctx context.Context, opts ...Option) (_ Connection, err error)

New connects to name and return name runtime holder

type DB 

type DB interface {
	cluster.Cluster

	// Name returns database name
	Name() string

	// Secure returns true if database connection is secure
	Secure() bool
}

type Error added in v3.4.2 

type Error interface {
	error

	Code() int32
	Name() string
}

func OperationErrorDescription added in v3.4.2 

func OperationErrorDescription(err error) Error

func TransportErrorDescription added in v3.4.2 

func TransportErrorDescription(err error) Error

type Option 

type Option func(ctx context.Context, db *db) error

func With 

func With(options ...config.Option) Option

func WithAccessTokenCredentials 

func WithAccessTokenCredentials(accessToken string) Option

func WithAnonymousCredentials 

func WithAnonymousCredentials() Option

func WithBalancingConfig 

func WithBalancingConfig(balancerConfig config.BalancerConfig) Option

func WithCertificate 

func WithCertificate(cert *x509.Certificate) Option

func WithCertificatesFromFile 

func WithCertificatesFromFile(caFile string) Option

func WithCertificatesFromPem 

func WithCertificatesFromPem(bytes []byte) Option

func WithConnectParams 

func WithConnectParams(params ConnectParams) Option

func WithConnectionString 

func WithConnectionString(connection string) Option

func WithCreateCredentialsFunc 

func WithCreateCredentialsFunc(createCredentials func(ctx context.Context) (credentials.Credentials, error)) Option

func WithCredentials 

func WithCredentials(c credentials.Credentials) Option

func WithDatabase added in v3.2.1 

func WithDatabase(database string) Option

func WithDialTimeout 

func WithDialTimeout(timeout time.Duration) Option

func WithDiscoveryInterval 

func WithDiscoveryInterval(discoveryInterval time.Duration) Option

func WithDriverConfigOptions 

func WithDriverConfigOptions(options ...config.Option) Option

func WithEndpoint added in v3.2.1 

func WithEndpoint(endpoint string) Option

func WithGrpcConnectionTTL 

func WithGrpcConnectionTTL(ttl time.Duration) Option

func WithLogger added in v3.3.0 

func WithLogger(details trace.Details, opts ...logger.Option) Option

func WithSessionPoolCreateSessionTimeout 

func WithSessionPoolCreateSessionTimeout(createSessionTimeout time.Duration) Option

func WithSessionPoolDeleteTimeout 

func WithSessionPoolDeleteTimeout(deleteTimeout time.Duration) Option

func WithSessionPoolIdleThreshold 

func WithSessionPoolIdleThreshold(idleThreshold time.Duration) Option

func WithSessionPoolKeepAliveMinSize 

func WithSessionPoolKeepAliveMinSize(keepAliveMinSize int) Option

func WithSessionPoolKeepAliveTimeout 

func WithSessionPoolKeepAliveTimeout(keepAliveTimeout time.Duration) Option

func WithSessionPoolSizeLimit 

func WithSessionPoolSizeLimit(sizeLimit int) Option

func WithTableConfigOption 

func WithTableConfigOption(option config.Option) Option

func WithTraceDriver 

func WithTraceDriver(trace trace.Driver) Option

WithTraceDriver returns deadline which has associated Driver with it.

func WithTraceTable 

func WithTraceTable(trace trace.Table) Option

WithTraceTable returns deadline which has associated Driver with it.

Source Files

View all Source files

Directories

Path Synopsis
internal
cmp
coordination
deadline
decimal
Package decimal provides tools for working with YDB's decimal types.
 Package decimal provides tools for working with YDB's decimal types.
dial
discovery
driver
driver/cluster
driver/cluster/balancer
driver/cluster/balancer/conn
driver/cluster/balancer/conn/endpoint
driver/cluster/balancer/conn/entry
driver/cluster/balancer/conn/info
driver/cluster/balancer/conn/list
driver/cluster/balancer/conn/stub
driver/cluster/balancer/state
driver/cluster/repeater
errors
feature
logger
meta
meta/credentials
operation
ratelimiter
response
scheme
table
table/scanner
timeutil
value
wg
wrap
ydbtest
Package ydbtest provides tools for stubbing ydb server up.
 Package ydbtest provides tools for stubbing ydb server up.
ydbtypes
Package ydbtypes provides tools for integration ydb types with go/types package.
 Package ydbtypes provides tools for integration ydb types with go/types package.
config
options
resultset
stats
types
timeutil
timeutil/timetest

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.