ydb

package module
v2.5.4 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2021 License: Apache-2.0 Imports: 38 Imported by: 2

README

ydb

YDB API client written in Go.

godoc

Overview

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

Prerequisites

Requires Go 1.13 or later.

Install

go get -u github.com/yandex-cloud/ydb-go-sdk/v2

Usage

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

// Determine timeout for connect or do nothing
connectCtx, cancel := context.WithTimeout(ctx, time.Second)
defer cancel()

// connect package helps to connect to database, returns connection object which
// provide necessary clients such as table.Client, scheme.Client, etc.
// All manipulations with the connection could be done without the connect package
db, err := connect.New(
    connectCtx,
    connect.MustConnectionString(
    	"grpcs://ydb-ru.yandex.net:2135/?database=/ru/home/username/db",
    ),
)
if err != nil {
    return fmt.Errorf("connect error: %w", err)
}
defer db.Close()

// Create session for execute queries
session, err := db.Table().CreateSession(ctx)
if err != nil {
    // handle error
}
defer session.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(),
)

// Execute text query without preparation and with given "autocommit"
// transaction control. That is, transaction will be commited without
// additional calls. Notice the "_" unused variable – it stands for created
// transaction during execution, but as said above, transaction is commited
// for us and we 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", ydb.OptionalValue(ydb.UTF8Value("test"))),
    ),
)
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.NextSet("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
}

This example can be tested as ydb/example/from_readme

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

	var res *table.Result
	// Retry() will call given OperationFunc with the following invariants:
	//  - previous operation failed with retriable error;
	//  - number of retries is under the limit (default to 10, see table.Retryer docs);
	//
	// Note that in case of prepared statements call to Prepare() must be made
	// inside the Operation body.
	err = table.Retry(ctx, db.Table().Pool(),
		table.OperationFunc(func(ctx context.Context, s *table.Session) (err error) {
			res, err = s.Execute(...)
			return
		}),
	)

That is, instead of manual creation of table.Session, we give a SessionPool such responsibility. It holds instances of active sessions and "pings" them periodically to keep them alive.

See table.Retryer docs for more information about retry options.

database/sql driver

There is a database/sql driver for the sql-based applications or those which by some reasons need to use additional layer of absctraction between user code and storage backend.

For more information please see the docs of ydb/ydbsql package which provides database/sql driver implementation.

Credentials

There are different variants to get ydb.Credentials object to get authorized. Usage examples can be found here at func credentials(...) ydb.Credentials.

Generating code

Overview

There is lot of boilerplate code for scanning values from query result and for passing values to prepare query. There is an experimental tool named ydbgen aimed to solve this.

Install ydbgen
go get -u github.com/yandex-cloud/ydb-go-sdk/v2/cmd/ydbgen

Currently it is possible to generate such things:

  • scanning values from result into a struct or slice of structs;
  • building query parameters from struct
  • building ydb's struct value from struct
  • building ydb's list value from slice of structs

The very short example could be like this:

package somepkg

//go:generate ydbgen

//ydb:gen scan
type User struct {
	Name string
	Age  int32
}

After running go generate path/to/somepkg/dir file with suffix _ydbgen.go will be generated. It will contain method Scan() for User type, as requested in the generate comment.

Configuration

Generation may be configured at three levels starting from top:

  • ydbgen binary flags (package level)
  • comment markers right before generation object in form of //ydb:set [key1:value1 [... keyN:valueN]] (type level)
  • struct tags (field level)

Each downstream level overrides options for its context.

For example, this code will generate all possible code for User struct with field Age type mapped to non-optional type, because the lowermost configuration level (which is struct tag) defines non-optional uint32 type:

//go:generate ydbgen -wrap optional

//ydb:gen
//ydb:set wrap:none
type User struct {
	Age int32 `ydb:"type:uint32,column:user_age"`
}
Binary flags
Flag Value Default Meaning
wrap optional + Wraps all mapped field types with optional type if no explicit tag is specified.
wrap none No wrapping performed.
seek column + Uses res.SeekItem() call to find out next field to scan.
seek position Uses res.NextItem() call to find out next field to scan.
Comment markers options

Options for comment markers are similar to flags, except the form of serialization.

Struct tags and values overview
Tag Value Default Meaning
type T Specifies which ydb primitive type must be used for this field.
type T? The same as above, but wraps T with optional type.
conv safe + Prepares only safe type conversions. Fail generation if conversion is not possible.
conv unsafe Prepares unsafe type conversions too.
conv assert Prepares safety assertions before type conversion.
column string Maps field to this column name.

Also the shorthand tags are possible: when using tag without key:value form, tag with - value is interpreted as field must be ignored; in other way it is interpreted as the column name.

Customization

There are few additional options existing for flexibility purposes.

Optional Types

Previously only basic Go types were mentioned as ones that able to be converted to ydb types. But it is possible generate code that maps defined type to YDB type (actually to basic Go type and then to YDB type). To make so, such type must provide two methods (when generation both getter and setters) – Get() (T, bool) and Set(T), where T is a basic Go type, and bool is a flag that indicates that value defined.

//go:generate ydbgen

//ydb:gen
type User struct {
	Name OptString
}

type OptString struct {
	Value   string
	Defined bool
}

func (s OptString) Get() (string, bool) {
	return s.Value, s.Defined
}
func (s *OptString) Set(v string) {
	*s = OptString{
		Value:   v,
		Defined: true,
	}
}

There is special package called ydb/opt for this purposes:

package main

import "github.com/yandex-cloud/ydb-go-sdk/v2/opt"

//go:generate ydbgen

//ydb:gen
type User struct {
	Name opt.String
}
Dealing with time.Time

There is additional feature that makes it easier to work with time.Time values and their conversion to YDB types:

//go:generate ydbgen

//ydb:gen
type User struct {
	Updated time.Time `ydb:"type:timestamp?"`
}
Dealing with container types.

ydbgen supports scanning and serializing container types such as List<T> or Struct<T>.

//go:generate ydbgen

//ydb:gen
type User struct {
	Tags []string `ydb:"type:list<string>"`
}

Example above will interpret value for tags column (or 0-th item, depending on the seek mode) as List<String>.

Note that for String type this is neccessary to inform ydbgen that it is not a container by setting type field tag.

For more info please look at ydb/examples/generation folder.

Examples

More examples are listed in ydb/examples directory.

Documentation

Index

Constants

View Source 
const (
	MaxGetConnTimeout    = 10 * time.Second
	ConnResetOfflineRate = uint64(10)
)
View Source 
const (
	FeatureEnabled  = internal.FeatureEnabled
	FeatureDisabled = internal.FeatureDisabled
)
View Source 
const (
	StatusUnknownStatus      = StatusCode(Ydb.StatusIds_STATUS_CODE_UNSPECIFIED)
	StatusBadRequest         = StatusCode(Ydb.StatusIds_BAD_REQUEST)
	StatusUnauthorized       = StatusCode(Ydb.StatusIds_UNAUTHORIZED)
	StatusInternalError      = StatusCode(Ydb.StatusIds_INTERNAL_ERROR)
	StatusAborted            = StatusCode(Ydb.StatusIds_ABORTED)
	StatusUnavailable        = StatusCode(Ydb.StatusIds_UNAVAILABLE)
	StatusOverloaded         = StatusCode(Ydb.StatusIds_OVERLOADED)
	StatusSchemeError        = StatusCode(Ydb.StatusIds_SCHEME_ERROR)
	StatusGenericError       = StatusCode(Ydb.StatusIds_GENERIC_ERROR)
	StatusTimeout            = StatusCode(Ydb.StatusIds_TIMEOUT)
	StatusBadSession         = StatusCode(Ydb.StatusIds_BAD_SESSION)
	StatusPreconditionFailed = StatusCode(Ydb.StatusIds_PRECONDITION_FAILED)
	StatusAlreadyExists      = StatusCode(Ydb.StatusIds_ALREADY_EXISTS)
	StatusNotFound           = StatusCode(Ydb.StatusIds_NOT_FOUND)
	StatusSessionExpired     = StatusCode(Ydb.StatusIds_SESSION_EXPIRED)
	StatusCancelled          = StatusCode(Ydb.StatusIds_CANCELLED)
	StatusUndetermined       = StatusCode(Ydb.StatusIds_UNDETERMINED)
	StatusUnsupported        = StatusCode(Ydb.StatusIds_UNSUPPORTED)
	StatusSessionBusy        = StatusCode(Ydb.StatusIds_SESSION_BUSY)
)

Errors describing unsusccessful operation status.

View Source 
const (
	RetryUnavailable = 1 << iota >> 1
	RetryAvailable
	RetryBackoff
	RetryDeleteSession
	RetryCheckSession
	RetryDropCache
)

Binary flags that used as RetryMode.

View Source 
const (
	TypeUnknown      = internal.TypeUnknown
	TypeBool         = internal.TypeBool
	TypeInt8         = internal.TypeInt8
	TypeUint8        = internal.TypeUint8
	TypeInt16        = internal.TypeInt16
	TypeUint16       = internal.TypeUint16
	TypeInt32        = internal.TypeInt32
	TypeUint32       = internal.TypeUint32
	TypeInt64        = internal.TypeInt64
	TypeUint64       = internal.TypeUint64
	TypeFloat        = internal.TypeFloat
	TypeDouble       = internal.TypeDouble
	TypeDate         = internal.TypeDate
	TypeDatetime     = internal.TypeDatetime
	TypeTimestamp    = internal.TypeTimestamp
	TypeInterval     = internal.TypeInterval
	TypeTzDate       = internal.TypeTzDate
	TypeTzDatetime   = internal.TypeTzDatetime
	TypeTzTimestamp  = internal.TypeTzTimestamp
	TypeString       = internal.TypeString
	TypeUTF8         = internal.TypeUTF8
	TypeYSON         = internal.TypeYSON
	TypeJSON         = internal.TypeJSON
	TypeUUID         = internal.TypeUUID
	TypeJSONDocument = internal.TypeJSONDocument
	TypeDyNumber     = internal.TypeDyNumber
)

Primitive types known by YDB.

View Source 
const (
	Version = "ydb-go-sdk/2.5.4"
)

Variables

View Source 
var (
	// ErrNilBalancerElement returned when requested on a nil balancer element.
	ErrNilBalancerElement = errors.New("nil balancer element")
	// ErrUnknownBalancerElement returned when requested on a unknown balancer element.
	ErrUnknownBalancerElement = errors.New("unknown balancer element")
	// ErrUnknownTypeOfBalancerElement returned when requested on a unknown type of balancer element.
	ErrUnknownTypeOfBalancerElement = errors.New("unknown type of balancer element")
)
View Source 
var (
	// ErrClusterClosed returned when requested on a closed cluster.
	ErrClusterClosed = errors.New("cluster closed")

	// ErrClusterEmpty returned when no connections left in cluster.
	ErrClusterEmpty = errors.New("cluster empty")

	// ErrUnknownEndpoint returned when no connections left in cluster.
	ErrUnknownEndpoint = errors.New("unknown endpoint")
)
View Source 
var (
	// DefaultDiscoveryInterval contains default duration between discovery
	// requests made by driver.
	DefaultDiscoveryInterval = time.Minute

	// DefaultBalancingMethod contains driver's default balancing algorithm.
	DefaultBalancingMethod = BalancingRandomChoice

	// ErrClosed is returned when operation requested on a closed driver.
	ErrClosed = errors.New("driver closed")

	// ErrNilConnection is returned when use nil preferred connection
	ErrNilConnection = errors.New("nil connection")
)
View Source 
var (
	// DefaultKeepaliveInterval contains default duration between grpc keepalive
	DefaultKeepaliveInterval = 5 * time.Minute
	MinKeepaliveInterval     = 1 * time.Minute
	DefaultGRPCMsgSize       = 64 * 1024 * 1024 // 64MB
)
View Source 
var (
	DefaultMaxRetries   = 10
	DefaultRetryChecker = RetryChecker{
		RetryNotFound: true,
	}
	// DefaultBackoff is a logarithmic backoff retry strategy.
	DefaultBackoff = LogBackoff{
		SlotDuration: time.Second,
		Ceiling:      6,
	}
)

Default parameters used by Retry() functions within different sub packages.

View Source 
var DefaultDecimal = Decimal(22, 9)
View Source 
var (
	// ErrCredentialsNoCredentials may be returned by Credentials implementations to
	// make driver act as if there no Credentials at all. That is, driver will
	// not send any token meta information during request.
	ErrCredentialsNoCredentials = errors.New("ydb: credentials: no credentials")
)
View Source 
var ErrOperationNotReady = errors.New("operation is not ready yet")

Functions

func AppendCertsFromFile added in v2.2.0 

func AppendCertsFromFile(certPool *x509.CertPool, caFile string) error

func Compare 

func Compare(l, r Value) (int, error)

Compare compares its operands. It returns -1, 0, 1 if l < r, l == r, l > r. Returns error if types are not comparable. Comparable types are all integer types, UUID, DyNumber, Float, Double, String, UTF8, Date, Datetime, Timestamp, Tuples and Lists. Primitive arguments are comparable if their types are the same. Optional type is comparable to underlying type, e.g. Optional<Optional<Float>> is comparable to Float. Null value is comparable to non-null value of the same type and is considered less than any non-null value. Tuples and Lists are comparable if their elements are comparable. Tuples and Lists are compared lexicographically. If tuples (lists) have different length and elements of the shorter tuple (list) are all equal to corresponding elements of the other tuple (list), than the shorter tuple (list) is considered less than the longer one.

func ContextConn 

func ContextConn(ctx context.Context) (conn *conn, backoffUseBalancer bool)

ContextConn returns the connection and connection use policy

func ContextCredentialsSourceInfo 

func ContextCredentialsSourceInfo(ctx context.Context) (sourceInfo string, ok bool)

func ContextOperationCancelAfter 

func ContextOperationCancelAfter(ctx context.Context) (d time.Duration, ok bool)

ContextOperationTimeout returns the timeout within given context after which YDB should try to cancel operation and return result regardless of the cancelation.

func ContextOperationTimeout 

func ContextOperationTimeout(ctx context.Context) (d time.Duration, ok bool)

ContextOperationTimeout returns the timeout within given context after which YDB should try to cancel operation and return result regardless of the cancelation.

func ContextWithoutDeadline 

func ContextWithoutDeadline(ctx context.Context) context.Context

ContextWithoutDeadline helps to clear derived context from deadline

func IsOpError 

func IsOpError(err error, code StatusCode) bool

IsOpError reports whether err is OpError with given code as the Reason.

func IsTransportError 

func IsTransportError(err error, code TransportErrorCode) bool

IsTransportError reports whether err is TransportError with given code as the Reason.

func NewAnonymousCredentials 

func NewAnonymousCredentials(sourceInfo string) *anonymousCredentials

func NewRepeater 

func NewRepeater(interval, timeout time.Duration, task func(ctx context.Context)) *repeater

NewRepeater creates and begins to execute task periodically.

func ReadConnStats 

func ReadConnStats(d Driver, f func(Endpoint, ConnStats))

func Unwrap added in v2.3.2 

func Unwrap(op Operation) (method string, req, res proto.Message)

func WaitBackoff 

func WaitBackoff(ctx context.Context, b Backoff, i int) error

WaitBackoff is a helper function that waits for i-th backoff b or ctx expiration. It returns non-nil error if and only if context expiration branch wins.

func WithCredentialsSourceInfo 

func WithCredentialsSourceInfo(ctx context.Context, sourceInfo string) context.Context

func WithDriverTrace 

func WithDriverTrace(ctx context.Context, t DriverTrace) context.Context

WithDriverTrace returns context which has associated DriverTrace with it.

func WithEndpointInfo 

func WithEndpointInfo(ctx context.Context, endpointInfo EndpointInfo) context.Context

WithEndpointInfo returns a copy of parent context with endpoint info and default connection use policy

func WithEndpointInfoAndPolicy 

func WithEndpointInfoAndPolicy(ctx context.Context, endpointInfo EndpointInfo, policy ConnUsePolicy) context.Context

WithEndpointInfo returns a copy of parent context with endopint info and custom connection use policy

func WithOperationCancelAfter 

func WithOperationCancelAfter(ctx context.Context, d time.Duration) context.Context

WithOperationCancelAfter returns a copy of parent context in which YDB operation cancel after parameter is set to d. If parent context cancelation timeout is smaller than d, parent context context is returned.

func WithOperationMode 

func WithOperationMode(ctx context.Context, m OperationMode) context.Context

WithOperationMode returns a copy of parent context in which YDB operation mode parameter is set to m. If parent context mode is set and is not equal to m, WithOperationMode will panic.

func WithOperationTimeout 

func WithOperationTimeout(ctx context.Context, d time.Duration) context.Context

WithOperationTimeout returns a copy of parent context in which YDB operation timeout parameter is set to d. If parent context timeout is smaller than d, parent context is returned.

func WithTraceID 

func WithTraceID(ctx context.Context, traceID string) context.Context

WithTraceID returns a copy of parent context with traceID

func WithUserAgent 

func WithUserAgent(ctx context.Context, userAgent string) context.Context

WithUserAgent returns a copy of parent context with custom user-agent info

func WithYdbCA 

func WithYdbCA(certPool *x509.CertPool) (_ *x509.CertPool, err error)

func WriteTypeStringTo 

func WriteTypeStringTo(buf *bytes.Buffer, t Type)

Types

type AuthTokenCredentials 

type AuthTokenCredentials struct {
	AuthToken string
	// contains filtered or unexported fields
}

AuthTokenCredentials implements Credentials interface with static authorization parameters.

func NewAuthTokenCredentials 

func NewAuthTokenCredentials(authToken string, sourceInfo string) *AuthTokenCredentials

func (AuthTokenCredentials) String 

func (a AuthTokenCredentials) String() string

Token implements Credentials.

func (AuthTokenCredentials) Token 

func (a AuthTokenCredentials) Token(_ context.Context) (string, error)

Token implements Credentials.

type Backoff 

type Backoff interface {
	// Wait maps index of the retry to a channel which fulfillment means that
	// delay is over.
	//
	// Note that retry index begins from 0 and 0-th index means that it is the
	// first retry attempt after an initial error.
	Wait(n int) <-chan time.Time
}

Backoff is the interface that contains logic of delaying operation retry.

type BackoffFunc 

type BackoffFunc func(n int) <-chan time.Time

BackoffFunc is an adatper to allow the use of ordinary functions as Backoff.

func (BackoffFunc) Wait 

func (f BackoffFunc) Wait(n int) <-chan time.Time

Wait implements Backoff interface.

type BalancingMethod 

type BalancingMethod uint

BalancingMethod encodes balancing method for driver configuration. 

const (
	BalancingUnknown BalancingMethod = iota
	BalancingRoundRobin
	BalancingP2C
	BalancingRandomChoice
)

type CallInfo 

type CallInfo interface {
	EndpointInfo
}

CallInfo is struct contained information about call

type ConnState 

type ConnState int8
const (
	ConnOffline ConnState = iota - 2
	ConnBanned
	ConnStateUnknown
	ConnOnline
)

func (ConnState) String 

func (s ConnState) String() string

type ConnStats 

type ConnStats struct {
	State        ConnState
	OpStarted    uint64
	OpFailed     uint64
	OpSucceed    uint64
	OpPerMinute  float64
	ErrPerMinute float64
	AvgOpTime    time.Duration
}

func (ConnStats) OpPending 

func (c ConnStats) OpPending() uint64

type ConnUsePolicy 

type ConnUsePolicy uint8
const (
	ConnUseDefault ConnUsePolicy = 1 << iota >> 1
	ConnUseBalancer
	ConnUseEndpoint

	ConnUseSmart = ConnUseBalancer | ConnUseEndpoint
)

type Credentials 

type Credentials interface {
	Token(context.Context) (string, error)
}

Credentials is an interface that contains options used to authorize a client.

func MultiCredentials 

func MultiCredentials(cs ...Credentials) Credentials

MultiCredentials creates Credentials which represents multiple ways of obtaining token. Its Token() method proxies call to the underlying credentials in order. When first successful call met, it returns. If there are no successful calls, it returns last error.

type CredentialsFunc 

type CredentialsFunc func(context.Context) (string, error)

CredentialsFunc is an adapter to allow the use of ordinary functions as Credentials.

func (CredentialsFunc) String 

func (f CredentialsFunc) String() string

Token implements Credentials.

func (CredentialsFunc) Token 

func (f CredentialsFunc) Token(ctx context.Context) (string, error)

Token implements Credentials.

type CustomScanner added in v2.5.0 

type CustomScanner interface {
	UnmarshalYDB(res RawScanner) error
}

CustomScanner scanning non-primitive yql types

type DialDoneInfo 

type DialDoneInfo struct {
	Context context.Context
	Address string
	Error   error
}

type DialStartInfo 

type DialStartInfo struct {
	Context context.Context
	Address string
}

type Dialer 

type Dialer struct {
	// DriverConfig is a driver configuration.
	DriverConfig *DriverConfig

	// TLSConfig specifies the TLS configuration to use for tls client.
	// If TLSConfig is zero then connections are insecure.
	TLSConfig *tls.Config

	// Timeout is the maximum amount of time a dial will wait for a connect to
	// complete.
	// If Timeout is zero then no timeout is used.
	Timeout time.Duration

	// Keepalive is the interval used to check whether inner connections are
	// still valid.
	// Dialer could increase keepalive interval if given value is too small.
	Keepalive time.Duration

	// NetDial is an optional function that may replace default network dialing
	// function such as net.Dial("tcp").
	// Deprecated: Use it for test purposes and special cases only. In most cases should be left empty.
	NetDial func(context.Context, string) (net.Conn, error)
}

Dialer contains options of dialing and initialization of particular ydb driver.

func (*Dialer) Dial 

func (d *Dialer) Dial(ctx context.Context, addr string) (_ Driver, err error)

Dial dials given addr and initializes driver instance on success.

type DiscoveryDoneInfo 

type DiscoveryDoneInfo struct {
	Context   context.Context
	Endpoints []Endpoint
	Error     error
}

type DiscoveryStartInfo 

type DiscoveryStartInfo struct {
	Context context.Context
}

type Driver 

type Driver interface {
	Call(context.Context, Operation) (CallInfo, error)
	StreamRead(context.Context, StreamOperation) (CallInfo, error)
	Close() error
}

Driver is an interface of YDB driver.

func Dial 

func Dial(ctx context.Context, addr string, c *DriverConfig) (Driver, error)

type DriverConfig 

type DriverConfig struct {
	// Database is a required database name.
	Database string

	// Credentials is an ydb client credentials.
	// In most cases Credentials are required.
	Credentials Credentials

	// Trace contains driver tracing options.
	Trace DriverTrace

	// RequestTimeout is the maximum amount of time a Call() will wait for an
	// operation to complete.
	// If RequestTimeout is zero then no timeout is used.
	RequestTimeout time.Duration

	// StreamTimeout is the maximum amount of time a StreamRead() will wait for
	// an operation to complete.
	// If StreamTimeout is zero then no timeout is used.
	StreamTimeout time.Duration

	// OperationTimeout is the maximum amount of time a YDB server will process
	// an operation. After timeout exceeds YDB will try to cancel operation and
	// regardless of the cancellation appropriate error will be returned to
	// the client.
	// If OperationTimeout is zero then no timeout is used.
	OperationTimeout time.Duration

	// OperationCancelAfter is the maximum amount of time a YDB server will process an
	// operation. After timeout exceeds YDB will try to cancel operation and if
	// it succeeds appropriate error will be returned to the client; otherwise
	// processing will be continued.
	// If OperationCancelAfter is zero then no timeout is used.
	OperationCancelAfter time.Duration

	// DiscoveryInterval is the frequency of background tasks of ydb endpoints
	// discovery.
	// If DiscoveryInterval is zero then the DefaultDiscoveryInterval is used.
	// If DiscoveryInterval is negative, then no background discovery prepared.
	DiscoveryInterval time.Duration

	// BalancingMethod is an algorithm used by the driver for endpoint
	// selection.
	// If BalancingMethod is zero then the DefaultBalancingMethod is used.
	BalancingMethod BalancingMethod

	// BalancingConfig is an optional configuration related to selected
	// BalancingMethod. That is, some balancing methods allow to be configured.
	BalancingConfig interface{}

	// PreferLocalEndpoints adds endpoint selection logic when local endpoints
	// are always used first.
	// When no alive local endpoints left other endpoints will be used.
	//
	// NOTE: some balancing methods (such as p2c) also may use knowledge of
	// endpoint's locality. Difference is that with PreferLocalEndpoints local
	// endpoints selected separately from others. That is, if there at least
	// one local endpoint it will be used regardless of its performance
	// indicators.
	//
	// NOTE: currently driver (and even ydb itself) does not track load factor
	// of each endpoint properly. Enabling this option may lead to the
	// situation, when all but one nodes in local datacenter become inactive
	// and all clients will overload this single instance very quickly. That
	// is, currently this option may be called as experimental.
	// You have been warned.
	PreferLocalEndpoints bool

	// RequestsType set an additional type hint to all requests.
	// It is needed only for debug purposes and advanced cases.
	RequestsType string

	// FastDial will make dialer return Driver as soon as 1st connection succeeds.
	// NB: it may be not the fastest node to serve requests.
	FastDial bool
}

DriverConfig contains driver configuration options.

type DriverTrace 

type DriverTrace struct {
	OnDial func(DialStartInfo) func(DialDoneInfo)

	OnGetConn func(GetConnStartInfo) func(GetConnDoneInfo)

	OnPessimization func(PessimizationStartInfo) func(PessimizationDoneInfo)

	// Only for background.
	TrackConnStart func(TrackConnStartInfo)
	TrackConnDone  func(TrackConnDoneInfo)

	OnGetCredentials func(GetCredentialsStartInfo) func(GetCredentialsDoneInfo)

	OnDiscovery func(DiscoveryStartInfo) func(DiscoveryDoneInfo)

	OnOperation     func(OperationStartInfo) func(OperationDoneInfo)
	OnOperationWait func(OperationWaitInfo)

	OnStream func(StreamStartInfo) func(StreamDoneInfo)

	OnStreamRecv func(StreamRecvStartInfo) func(StreamRecvDoneInfo)
}

func ContextDriverTrace 

func ContextDriverTrace(ctx context.Context) DriverTrace

ContextDriverTrace returns DriverTrace associated with ctx. If there is no DriverTrace associated with ctx then zero value of DriverTrace is returned.

func (DriverTrace) Compose 

func (t DriverTrace) Compose(x DriverTrace) (ret DriverTrace)

Compose returns a new DriverTrace which has functional fields composed both from t and x.

type Duration deprecated 

type Duration time.Duration

Deprecated: Use standard time.Time instead This type will be removed at next major release

func (Duration) Interval 

func (d Duration) Interval() int64

type Endpoint 

type Endpoint struct {
	Addr       string
	Port       int
	LoadFactor float32
	Local      bool
}

type EndpointInfo 

type EndpointInfo interface {
	Conn() *conn
	Address() string
}

EndpointInfo is struct contained information about endpoint

type FeatureFlag 

type FeatureFlag = internal.FeatureFlag

type GetConnDoneInfo 

type GetConnDoneInfo struct {
	Context context.Context
	Address string
	Error   error
}

type GetConnStartInfo 

type GetConnStartInfo struct {
	Context context.Context
}

type GetCredentialsDoneInfo 

type GetCredentialsDoneInfo struct {
	Context context.Context
	Token   bool
	Error   error
}

type GetCredentialsStartInfo 

type GetCredentialsStartInfo struct {
	Context context.Context
}

type Issue 

type Issue struct {
	Message  string
	Code     uint32
	Severity uint32
}

type IssueIterator 

type IssueIterator []*Ydb_Issue.IssueMessage

func (IssueIterator) Get 

func (it IssueIterator) Get(i int) (issue Issue, nested IssueIterator)

func (IssueIterator) Len 

func (it IssueIterator) Len() int

type LogBackoff 

type LogBackoff struct {
	// SlotDuration is a size of a single time slot used in backoff delay
	// calculation.
	// If SlotDuration is less or equal to zero, then the time.Second value is
	// used.
	SlotDuration time.Duration

	// Ceiling is a maximum degree of backoff delay growth.
	// If Ceiling is less or equal to zero, then the default ceiling of 1 is
	// used.
	Ceiling uint

	// JitterLimit controls fixed and random portions of backoff delay.
	// Its value can be in range [0, 1].
	// If JitterLimit is non zero, then the backoff delay will be equal to (F + R),
	// where F is a result of multiplication of this value and calculated delay
	// duration D; and R is a random sized part from [0,(D - F)].
	JitterLimit float64
}

LogBackoff contains logarithmic backoff policy.

func (LogBackoff) Delay 

func (b LogBackoff) Delay(i int) time.Duration

Delay returns mapping of i to delay.

func (LogBackoff) Wait 

func (b LogBackoff) Wait(n int) <-chan time.Time

Wait implements Backoff interface.

type Method 

type Method string

Method represents rpc method.

func (Method) Name 

func (m Method) Name() (s string)

Name returns the rpc method name.

func (Method) Service 

func (m Method) Service() (s string)

Service returns the rpc service name.

func (Method) Split 

func (m Method) Split() (service, method string)

Split returns service name and method.

type NoOpResponse added in v2.4.0 

type NoOpResponse = internal.NoOpResponse

type OpError 

type OpError struct {
	Reason StatusCode
	// contains filtered or unexported fields
}

OpError reports about operation fail.

func (*OpError) Error 

func (e *OpError) Error() string

func (*OpError) Issues 

func (e *OpError) Issues() IssueIterator

type OpResponse added in v2.4.0 

type OpResponse = internal.OpResponse

type Operation added in v2.3.2 

type Operation = internal.Operation

func Wrap added in v2.3.2 

func Wrap(method string, req, res proto.Message) Operation

func WrapWithResponse added in v2.5.0 

func WrapWithResponse(method string, req proto.Message, resp Response) Operation

type OperationDoneInfo 

type OperationDoneInfo struct {
	Context context.Context
	Address string
	Method  Method
	Params  OperationParams
	OpID    string
	Issues  IssueIterator
	Error   error
}

type OperationMode 

type OperationMode uint
const (
	OperationModeUnknown OperationMode = iota
	OperationModeSync
	OperationModeAsync
)

func ContextOperationMode 

func ContextOperationMode(ctx context.Context) (m OperationMode, ok bool)

ContextOperationMode returns the mode of YDB operation within given context.

func (OperationMode) String 

func (m OperationMode) String() string

type OperationParams 

type OperationParams struct {
	Timeout     time.Duration
	CancelAfter time.Duration
	Mode        OperationMode
}

func (OperationParams) Empty 

func (p OperationParams) Empty() bool

type OperationStartInfo 

type OperationStartInfo struct {
	Context context.Context
	Address string
	Method  Method
	Params  OperationParams
}

type OperationWaitInfo 

type OperationWaitInfo struct {
	Context context.Context
	Address string
	Method  Method
	Params  OperationParams
	OpID    string
}

type P2CConfig 

type P2CConfig struct {
	// PreferLocal reports whether p2c balancer should prefer local endpoint
	// when all other runtime indicators are the same (such as error rate or
	// average response time).
	PreferLocal bool

	// OpTimeThreshold specifies such difference between endpoint average
	// operation time when it becomes significant to be used during comparison.
	OpTimeThreshold time.Duration
}

type PessimizationDoneInfo 

type PessimizationDoneInfo struct {
	Context context.Context
	Address string
	Error   error
}

type PessimizationStartInfo 

type PessimizationStartInfo struct {
	Context context.Context
	Address string
	Cause   error
}

type RawScanner added in v2.5.0 

type RawScanner interface {
	HasItems() bool
	HasNextItem() bool

	// NextItem selects next item to parse in the current row.
	// It returns false if there are no more items in the row.
	//
	// Note that NextItem() differs from NextRow() and NextSet() – if it return
	// false it fails the Result such that no further operations may be processed.
	// That is, res.Err() becomes non-nil.
	NextItem() (ok bool)

	// SeekItem finds the column with given name in the result set and selects
	// appropriate item to parse in the current row.
	SeekItem(name string) bool
	Path() string
	WritePathTo(w io.Writer) (n int64, err error)
	Type() Type
	Bool() (v bool)
	Int8() (v int8)
	Uint8() (v uint8)
	Int16() (v int16)
	Uint16() (v uint16)
	Int32() (v int32)
	Uint32() (v uint32)
	Int64() (v int64)
	Uint64() (v uint64)
	Float() (v float32)
	Double() (v float64)
	Date() (v uint32)
	Datetime() (v uint32)
	Timestamp() (v uint64)
	Interval() (v int64)
	TzDate() (v string)
	TzDatetime() (v string)
	TzTimestamp() (v string)
	String() (v []byte)
	UTF8() (v string)
	YSON() (v string)
	JSON() (v string)
	UUID() (v [16]byte)
	JSONDocument() (v string)
	DyNumber() (v string)
	OBool() (v bool)
	OInt8() (v int8)
	OUint8() (v uint8)
	OInt16() (v int16)
	OUint16() (v uint16)
	OInt32() (v int32)
	OUint32() (v uint32)
	OInt64() (v int64)
	OUint64() (v uint64)
	OFloat() (v float32)
	ODouble() (v float64)
	ODate() (v uint32)
	ODatetime() (v uint32)
	OTimestamp() (v uint64)
	OInterval() (v int64)
	OTzDate() (v string)
	OTzDatetime() (v string)
	OTzTimestamp() (v string)
	OString() (v []byte)
	OUTF8() (v string)
	OYSON() (v string)
	OJSON() (v string)
	OUUID() (v [16]byte)
	OJSONDocument() (v string)
	ODyNumber() (v string)

	// Any returns any pritmitive value.
	// Currently it may return one of this types:
	//
	//   bool
	//   int8
	//   uint8
	//   int16
	//   uint16
	//   int32
	//   uint32
	//   int64
	//   uint64
	//   float32
	//   float64
	//   []byte
	//   string
	//   [16]byte
	//
	Any() interface{}
	Value() Value

	// ListIn interprets current item under scan as a ydb's list.
	// It returns the size of the nested items.
	// If current item under scan is not a list type, it returns -1.
	ListIn() (size int)

	// ListItem selects current item i-th element as an item to scan.
	// ListIn() must be called before.
	ListItem(i int)

	// ListOut leaves list entered before by ListIn() call.
	ListOut()

	// TupleIn interprets current item under scan as a ydb's tuple.
	// It returns the size of the nested items.
	TupleIn() (size int)

	// TupleItem selects current item i-th element as an item to scan.
	// Note that TupleIn() must be called before.
	// It panics if it is out of bounds.
	TupleItem(i int)

	// TupleOut leaves tuple entered before by TupleIn() call.
	TupleOut()

	// StructIn interprets current item under scan as a ydb's struct.
	// It returns the size of the nested items – the struct fields values.
	// If there is no current item under scan it returns -1.
	StructIn() (size int)

	// StructField selects current item i-th field value as an item to scan.
	// Note that StructIn() must be called before.
	// It panics if i is out of bounds.
	StructField(i int) (name string)

	// StructOut leaves struct entered before by StructIn() call.
	StructOut()

	// DictIn interprets current item under scan as a ydb's dict.
	// It returns the size of the nested items pairs.
	// If there is no current item under scan it returns -1.
	DictIn() (size int)

	// DictKey selects current item i-th pair key as an item to scan.
	// Note that DictIn() must be called before.
	// It panics if i is out of bounds.
	DictKey(i int)

	// DictPayload selects current item i-th pair value as an item to scan.
	// Note that DictIn() must be called before.
	// It panics if i is out of bounds.
	DictPayload(i int)

	// DictOut leaves dict entered before by DictIn() call.
	DictOut()

	// Variant unwraps current item under scan interpreting it as Variant<T> type.
	// It returns non-empty name of a field that is filled for struct-based
	// variant.
	// It always returns an index of filled field of a T.
	Variant() (name string, index uint32)

	// Decimal returns decimal value represented by big-endian 128 bit signed integer.
	Decimal(t Type) (v [16]byte)
	ODecimal(t Type) (v [16]byte)

	// UnwrapDecimal returns decimal value represented by big-endian 128 bit signed
	// integer and its type information.
	UnwrapDecimal() (v [16]byte, precision, scale uint32)

	// Unwrap unwraps current item under scan interpreting it as Optional<T> type.
	Unwrap()
}

RawScanner scanning non-primitive yql types

type Response added in v2.4.0 

type Response = internal.Response

func WrapNoOpResponse added in v2.4.0 

func WrapNoOpResponse(resp NoOpResponse) Response

func WrapOpResponse added in v2.4.0 

func WrapOpResponse(resp OpResponse) Response

type RetryChecker 

type RetryChecker struct {
	// RetryNotFound reports whether Repeater must retry ErrNotFound errors.
	RetryNotFound bool
}

RetryChecker contains options of checking errors returned by YDB for ability to retry provoked operation.

func (*RetryChecker) Check 

func (r *RetryChecker) Check(err error) (m RetryMode)

Check returns retry mode for err.

type RetryMode 

type RetryMode uint32

RetryMode reports whether operation is able to be retried and with which properties.

func (RetryMode) MustBackoff 

func (m RetryMode) MustBackoff() bool

func (RetryMode) MustCheckSession 

func (m RetryMode) MustCheckSession() bool

func (RetryMode) MustDeleteSession 

func (m RetryMode) MustDeleteSession() bool

func (RetryMode) MustDropCache 

func (m RetryMode) MustDropCache() bool

func (RetryMode) Retriable 

func (m RetryMode) Retriable() bool

type StatusCode 

type StatusCode int32

StatusCode reports unsuccessful operation status code.

func (StatusCode) String 

func (e StatusCode) String() string

type StreamDoneInfo 

type StreamDoneInfo struct {
	Context context.Context
	Address string
	Method  Method
	Error   error
}

type StreamOperation added in v2.3.2 

type StreamOperation = internal.StreamOperation

func WrapStreamOperation added in v2.3.2 

func WrapStreamOperation(
	method string, req proto.Message,
	resp StreamOperationResponse,
	p func(error),
) StreamOperation

type StreamOperationResponse added in v2.3.2 

type StreamOperationResponse = internal.StreamOperationResponse

func UnwrapStreamOperation added in v2.3.2 

func UnwrapStreamOperation(op StreamOperation) (
	method string, req proto.Message,
	resp StreamOperationResponse,
	processor func(error),
)

type StreamRecvDoneInfo 

type StreamRecvDoneInfo struct {
	Context context.Context
	Address string
	Method  Method
	Issues  IssueIterator
	Error   error
}

type StreamRecvStartInfo 

type StreamRecvStartInfo struct {
	Context context.Context
	Address string
	Method  Method
}

type StreamStartInfo 

type StreamStartInfo struct {
	Context context.Context
	Address string
	Method  Method
}

type StructOption 

type StructOption func(*tStructType)

func StructField 

func StructField(name string, typ Type) StructOption

type StructValueOption 

type StructValueOption func(*tStructValueProto)

func StructFieldValue 

func StructFieldValue(name string, value Value) StructValueOption

type Time deprecated 

type Time time.Time

Deprecated: Use standard time.Time instead This type will be removed at next major release

func (Time) Date 

func (t Time) Date() uint32
func (t Time) String() string {
	return time.Time(t).String()
}

func (Time) Datetime 

func (t Time) Datetime() uint32

func (*Time) FromDate 

func (t *Time) FromDate(x uint32) error

func (*Time) FromDatetime 

func (t *Time) FromDatetime(x uint32) error

func (*Time) FromTimestamp 

func (t *Time) FromTimestamp(x uint64) error

func (*Time) FromTzDate 

func (t *Time) FromTzDate(x string) error

func (*Time) FromTzDatetime 

func (t *Time) FromTzDatetime(x string) error

func (*Time) FromTzTimestamp 

func (t *Time) FromTzTimestamp(x string) error

func (Time) Timestamp 

func (t Time) Timestamp() uint64

func (Time) TzDate 

func (t Time) TzDate() string

func (Time) TzDatetime 

func (t Time) TzDatetime() string

func (Time) TzTimestamp 

func (t Time) TzTimestamp() string

type TrackConnDoneInfo 

type TrackConnDoneInfo struct {
	Address string
}

type TrackConnStartInfo 

type TrackConnStartInfo struct {
	Address string
}

type TransportError 

type TransportError struct {
	Reason TransportErrorCode
	// contains filtered or unexported fields
}

func (*TransportError) Error 

func (t *TransportError) Error() string

func (*TransportError) Unwrap 

func (t *TransportError) Unwrap() error

type TransportErrorCode 

type TransportErrorCode int32
const (
	TransportErrorUnknownCode TransportErrorCode = iota
	TransportErrorCanceled
	TransportErrorUnknown
	TransportErrorInvalidArgument
	TransportErrorDeadlineExceeded
	TransportErrorNotFound
	TransportErrorAlreadyExists
	TransportErrorPermissionDenied
	TransportErrorResourceExhausted
	TransportErrorFailedPrecondition
	TransportErrorAborted
	TransportErrorOutOfRange
	TransportErrorUnimplemented
	TransportErrorInternal
	TransportErrorUnavailable
	TransportErrorDataLoss
	TransportErrorUnauthenticated
)

func (TransportErrorCode) String 

func (t TransportErrorCode) String() string

type Type 

type Type interface {
	internal.T
}

Type describes YDB data type.

func Decimal 

func Decimal(precision, scale uint32) Type

func List 

func List(T Type) Type

func Optional 

func Optional(T Type) Type

func Struct 

func Struct(opts ...StructOption) Type

func Tuple 

func Tuple(elems ...Type) Type

func Variant 

func Variant(x Type) Type

func Void 

func Void() Type

type Value 

type Value interface {
	internal.V
}

func BoolValue 

func BoolValue(v bool) Value

func DateValue 

func DateValue(v uint32) Value

func DateValueFromTime added in v2.4.0 

func DateValueFromTime(v time.Time) Value

func DatetimeValue 

func DatetimeValue(v uint32) Value

func DatetimeValueFromTime added in v2.4.0 

func DatetimeValueFromTime(v time.Time) Value

func DecimalValue 

func DecimalValue(t Type, v [16]byte) Value

DecimalValue creates decimal value of given type t and value v. Note that v interpreted as big-endian int128.

func DictValue 

func DictValue(pairs ...Value) Value

func DoubleValue 

func DoubleValue(v float64) Value

func DyNumberValue 

func DyNumberValue(v string) Value

func FloatValue 

func FloatValue(v float32) Value

func Int16Value 

func Int16Value(v int16) Value

func Int32Value 

func Int32Value(v int32) Value

func Int64Value 

func Int64Value(v int64) Value

func Int8Value 

func Int8Value(v int8) Value

func IntervalValue 

func IntervalValue(v int64) Value

func IntervalValueFromDuration added in v2.4.0 

func IntervalValueFromDuration(v time.Duration) Value

func JSONDocumentValue 

func JSONDocumentValue(v string) Value

func JSONDocumentValueFromBytes added in v2.4.0 

func JSONDocumentValueFromBytes(v []byte) Value

func JSONValue 

func JSONValue(v string) Value

func JSONValueFromBytes added in v2.4.0 

func JSONValueFromBytes(v []byte) Value

func ListValue 

func ListValue(vs ...Value) Value

func NullValue 

func NullValue(t Type) Value

func OptionalValue 

func OptionalValue(v Value) Value

func StringValue 

func StringValue(v []byte) Value

func StringValueFromString added in v2.4.0 

func StringValueFromString(v string) Value

func StructValue 

func StructValue(opts ...StructValueOption) Value

func TimestampValue 

func TimestampValue(v uint64) Value

func TimestampValueFromTime added in v2.4.0 

func TimestampValueFromTime(v time.Time) Value

func TupleValue 

func TupleValue(vs ...Value) Value

func TzDateValue 

func TzDateValue(v string) Value

func TzDateValueFromTime added in v2.4.0 

func TzDateValueFromTime(v time.Time) Value

func TzDatetimeValue 

func TzDatetimeValue(v string) Value

func TzDatetimeValueFromTime added in v2.4.0 

func TzDatetimeValueFromTime(v time.Time) Value

func TzTimestampValue 

func TzTimestampValue(v string) Value

func TzTimestampValueFromTime added in v2.4.0 

func TzTimestampValueFromTime(v time.Time) Value

func UTF8Value 

func UTF8Value(v string) Value

func UUIDValue 

func UUIDValue(v [16]byte) Value

func Uint16Value 

func Uint16Value(v uint16) Value

func Uint32Value 

func Uint32Value(v uint32) Value

func Uint64Value 

func Uint64Value(v uint64) Value

func Uint8Value 

func Uint8Value(v uint8) Value

func VariantValue 

func VariantValue(v Value, i uint32, variantT Type) Value

func VoidValue 

func VoidValue() Value

func YSONValue 

func YSONValue(v string) Value

func YSONValueFromBytes added in v2.4.0 

func YSONValueFromBytes(v []byte) Value

func ZeroValue 

func ZeroValue(t Type) Value

type WG 

type WG interface {
	Done()
	Wait()
	Add(delta int)
}

wrap sync.WaitGroup to allow for 'wait 1st' logic

Source Files

View all Source files

Directories

Path Synopsis
api
grpc/Ydb_Coordination_V1
grpc/Ydb_Discovery_V1
grpc/Ydb_Export_V1
grpc/Ydb_Import_V1
grpc/Ydb_RateLimiter_V1
grpc/Ydb_Scheme_V1
grpc/Ydb_Scripting_V1
grpc/Ydb_Table_V1
grpc/draft/Ydb_Experimental_V1
grpc/draft/Ydb_PersQueue_V1
protos/Ydb
protos/Ydb_Coordination
protos/Ydb_Discovery
protos/Ydb_Experimental
protos/Ydb_Export
protos/Ydb_Import
protos/Ydb_Issue
protos/Ydb_Operations
protos/Ydb_PersQueue_ClusterDiscovery
protos/Ydb_PersQueue_V1
protos/Ydb_RateLimiter
protos/Ydb_S3Internal
protos/Ydb_Scheme
protos/Ydb_Scripting
protos/Ydb_Table
protos/Ydb_TableStats
iam
Package iam provides interface for retrieving and caching iam tokens.
 Package iam provides interface for retrieving and caching iam tokens.
metadata
cmd
ydbgen
ydbgen/tests
Package decimal provides tools for working with YDB's decimal type.
 Package decimal provides tools for working with YDB's decimal type.
example
auth/access_token_credentials
auth/anonymous_credentials
auth/environ
auth/metadata_credentials
auth/service_account_credentials
basic_example
basic_example_v1
batch_upload
bulk_upsert
containers
ddl
decimal
from_readme
generation
healthcheck
internal/cli
pagination
partitioning_policies
read_table
secondary_index
secondary_index_builtin
ttl
ttl_readtable
url-shortener
cache/lru
result
stats
tracetest
traceutil
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.
Package opt contains go basic types wrappers to be used when dealing with optional types.
 Package opt contains go basic types wrappers to be used when dealing with optional types.
timetest
Package ydbsql provides integration of YDB table API with database/sql driver interface.
 Package ydbsql provides integration of YDB table API with database/sql driver interface.

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.