ydb

README

ydb

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

   // Determine timeout for connect or do nothing
   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,
      connectParams,
	  ydb.WithConnectionString(ydb.ConnectionString(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 *table.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 := c.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 := session.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
   }
   // 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("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. Usage examples can be found here.

Examples

More examples are listed in examples repository.

Documentation

Index

• Constants
• func IsOperationError(err error) (ok bool, code int32, name string)
• func IsStatusAlreadyExistsError(err error) bool
• func IsStatusNotFoundError(err error) bool
• func IsStatusSchemeError(err error) bool
• func IsTimeoutError(err error) bool
• func IsTransportError(err error) (ok bool, code int32, name string)
• func IterateByIssues(err error, it func(message string, code uint32, severity uint32))
• type ConnectParams
  • func ConnectionString(uri string) (ConnectParams, error)
  • func EndpointDatabase(endpoint string, database string, secure bool) ConnectParams
  • func MustConnectionString(uri string) ConnectParams
• type Connection
  • func New(ctx context.Context, opts ...Option) (_ Connection, err error)
• type DB
• type Option
  • func With(options ...config.Option) Option
  • func WithAccessTokenCredentials(accessToken string) Option
  • func WithAnonymousCredentials() Option
  • func WithBalancingConfig(balancerConfig config.BalancerConfig) Option
  • func WithCertificate(cert *x509.Certificate) Option
  • func WithCertificatesFromFile(caFile string) Option
  • func WithCertificatesFromPem(bytes []byte) Option
  • func WithConnectParams(params ConnectParams) Option
  • func WithConnectionString(connection string) Option
  • func WithCreateCredentialsFunc(createCredentials func(ctx context.Context) (credentials.Credentials, error)) Option
  • func WithCredentials(c credentials.Credentials) Option
  • func WithDialTimeout(timeout time.Duration) Option
  • func WithDiscoveryInterval(discoveryInterval time.Duration) Option
  • func WithDriverConfigOptions(options ...config.Option) Option
  • func WithGrpcConnectionTTL(ttl time.Duration) Option
  • func WithSessionPoolCreateSessionTimeout(createSessionTimeout time.Duration) Option
  • func WithSessionPoolDeleteTimeout(deleteTimeout time.Duration) Option
  • func WithSessionPoolIdleThreshold(idleThreshold time.Duration) Option
  • func WithSessionPoolKeepAliveMinSize(keepAliveMinSize int) Option
  • func WithSessionPoolKeepAliveTimeout(keepAliveTimeout time.Duration) Option
  • func WithSessionPoolSizeLimit(sizeLimit int) Option
  • func WithTableConfigOption(option config.Option) Option
  • func WithTraceDriver(trace trace.Driver) Option
  • func WithTraceTable(trace trace.Table) Option

Constants

const Version = meta.Version

Version alias for except cycle import

Functions

func IsOperationError

func IsOperationError(err error) (ok bool, code int32, name string)

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) (ok bool, code int32, name string)

func IterateByIssues

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

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

func WithDialTimeout(timeout time.Duration) Option

func WithDiscoveryInterval

func WithDiscoveryInterval(discoveryInterval time.Duration) Option

func WithDriverConfigOptions

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

func WithGrpcConnectionTTL

func WithGrpcConnectionTTL(ttl time.Duration) 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.