v3 – github.com/ydb-platform/ydb-go-sdk/v3 Index | Examples | Files | Directories

package ydb

import "github.com/ydb-platform/ydb-go-sdk/v3"

Package ydb-go-sdk - native Go's driver for YDB.

Supports table, discovery, coordination, ratelimiter, scheme and scripting clients for YDB. YDB is an open-source Distributed SQL Database that combines high availability and scalability with strict consistency and ACID transactions.

Example (Discovery)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpcs://localhost:2135/?database=/local")
	if err != nil {
		fmt.Printf("failed to connect: %v", err)
		return
	}
	defer db.Close(ctx) // cleanup resources
	endpoints, err := db.Discovery().Discover(ctx)
	if err != nil {
		fmt.Printf("discover failed: %v", err)
		return
	}
	fmt.Printf("%s endpoints:\n", db.Name())
	for i, e := range endpoints {
		fmt.Printf("%d) %s\n", i, e.String())
	}
}
Example (Scripting)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpcs://localhost:2135/?database=/local")
	if err != nil {
		fmt.Printf("failed to connect: %v", err)
		return
	}
	defer db.Close(ctx) // cleanup resources
	if err = retry.Retry(ctx, func(ctx context.Context) (err error) {
		res, err := db.Scripting().Execute(
			ctx,
			"SELECT 1+1",
			table.NewQueryParameters(),
		)
		if err != nil {
			return err
		}
		defer res.Close() // cleanup resources
		if !res.NextResultSet(ctx) {
			return retry.RetryableError(
				fmt.Errorf("no result sets"),
				retry.WithBackoff(retry.TypeNoBackoff),
			)
		}
		if !res.NextRow() {
			return retry.RetryableError(
				fmt.Errorf("no rows"),
				retry.WithBackoff(retry.TypeSlowBackoff),
			)
		}
		var sum int32
		if err = res.Scan(&sum); err != nil {
			return fmt.Errorf("scan failed: %w", err)
		}
		if sum != 2 {
			return fmt.Errorf("unexpected sum: %v", sum)
		}
		return res.Err()
	}, retry.WithIdempotent(true)); err != nil {
		fmt.Printf("Execute failed: %v", err)
	}
}
Example (Table)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpcs://localhost:2135/?database=/local")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close(ctx) // cleanup resources
	var (
		query = `SELECT 42 as id, "my string" as myStr`
		id    int32  // required value
		myStr string // optional value
	)
	err = db.Table().Do( // Do retry operation on errors with best effort
		ctx, // context manage exiting from Do
		func(ctx context.Context, s table.Session) (err error) { // retry operation
			_, res, err := s.Execute(ctx, table.DefaultTxControl(), query, nil)
			if err != nil {
				return err // for auto-retry with driver
			}
			defer res.Close()                                // cleanup resources
			if err = res.NextResultSetErr(ctx); err != nil { // check single result set and switch to it
				return err // for auto-retry with driver
			}
			for res.NextRow() { // iterate over rows
				err = res.ScanNamed(
					named.Required("id", &id),
					named.OptionalWithDefault("myStr", &myStr),
				)
				if err != nil {
					return err // generally scan error not retryable, return it for driver check error
				}
				log.Printf("id=%v, myStr='%s'\n", id, myStr)
			}
			return res.Err() // return finally result error for auto-retry with driver
		},
	)
	if err != nil {
		log.Printf("unexpected error: %v", err)
	}
}

Index

Examples

Constants 

const Version = meta.Version

Version reports current version of sdk

Functions

func GRPCConn 

func GRPCConn(conn Connection) grpc.ClientConnInterface

GRPCConn casts ydb.Connection to grpc.ClientConnInterface for executing unary and streaming RPC over internal driver balancer.

Warning: for connect to driver-unsupported YDB services

func IsOperationError 

func IsOperationError(err error, codes ...Ydb.StatusIds_StatusCode) bool

IsOperationError reports whether any error is an operation error with one of passed codes. If codes not defined IsOperationError returns true on error is an operation error.

func IsOperationErrorAlreadyExistsError 

func IsOperationErrorAlreadyExistsError(err error) bool

IsOperationErrorAlreadyExistsError checks whether given err is an operation error with code AlreadyExistsError

func IsOperationErrorNotFoundError 

func IsOperationErrorNotFoundError(err error) bool

IsOperationErrorNotFoundError checks whether given err is an operation error with code NotFoundError

func IsOperationErrorOverloaded 

func IsOperationErrorOverloaded(err error) bool

IsOperationErrorOverloaded checks whether given err is an operation error with code Overloaded

func IsOperationErrorSchemeError 

func IsOperationErrorSchemeError(err error) bool

IsOperationErrorSchemeError checks whether given err is an operation error with code SchemeError

func IsOperationErrorUnavailable 

func IsOperationErrorUnavailable(err error) bool

IsOperationErrorUnavailable checks whether given err is an operation error with code Unavailable

func IsRatelimiterAcquireError 

func IsRatelimiterAcquireError(err error) bool

IsRatelimiterAcquireError checks whether given err is an ratelimiter acquire error

func IsTimeoutError 

func IsTimeoutError(err error) bool

IsTimeoutError checks whether given err is a some timeout error (context, transport or operation).

func IsTransportError 

func IsTransportError(err error, codes ...grpcCodes.Code) bool

IsTransportError checks whether given err is a transport (grpc) error.

func IsYdbError 

func IsYdbError(err error) bool

IsYdbError reports when given error is and ydb error (transport, operation or internal driver error)

func IterateByIssues 

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

IterateByIssues helps to iterate over internal issues of operation error.

func ToRatelimiterAcquireError 

func ToRatelimiterAcquireError(err error) ratelimiter.AcquireError

ToRatelimiterAcquireError casts given err to ratelimiter.AcquireError. If given err is not ratelimiter acquire error - returns nil

func WithOperationCancelAfter 

func WithOperationCancelAfter(ctx context.Context, operationCancelAfter 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 cancellation timeout is smaller than d, parent context is returned.

func WithOperationTimeout 

func WithOperationTimeout(ctx context.Context, operationTimeout 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 WithRequestType 

func WithRequestType(ctx context.Context, requestType string) context.Context

WithRequestType returns a copy of parent context with custom request type

func WithTraceID 

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

WithTraceID returns a copy of parent context with traceID

Types

type Connection 

type Connection interface {
	// Endpoint returns initial endpoint
	Endpoint() string

	// Name returns database name
	Name() string

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

	// Close closes connection and clear resources
	Close(ctx context.Context) error

	// Table returns table client
	Table() table.Client

	// Scheme returns scheme client
	Scheme() scheme.Client

	// Coordination returns coordination client
	Coordination() coordination.Client

	// Ratelimiter returns ratelimiter client
	Ratelimiter() ratelimiter.Client

	// Discovery returns discovery client
	Discovery() discovery.Client

	// Scripting returns scripting client
	Scripting() scripting.Client

	// With makes child connection with the same options and another options
	With(ctx context.Context, opts ...Option) (Connection, error)
}

Connection interface provide access to YDB service clients Interface and list of clients may be changed in the future

This interface is central part for access to various systems embedded to ydb through one configured connection method.

func New 

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

New connects to database and return driver runtime holder

Deprecated: use Open with required param connectionString instead

func Open 

func Open(ctx context.Context, dsn string, opts ...Option) (_ Connection, err error)

Open connects to database by DSN and return driver runtime holder

DSN accept connection string like 

"grpc[s]://{endpoint}/?database={database}[&param=value]"

See sugar.DSN helper for make dsn from endpoint and database

Example

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpc://localhost:2135?database=/local")
	if err != nil {
		fmt.Printf("connection failed: %v", err)
	}
	defer db.Close(ctx) // cleanup resources
	fmt.Printf("connected to %s, database '%s'", db.Endpoint(), db.Name())
}
Example (Advanced)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(
		ctx,
		"grpc://localhost:2135?database=/local",
		ydb.WithAnonymousCredentials(),
		ydb.WithBalancer(
			balancers.PreferLocationsWithFallback(
				balancers.RandomChoice(), "a", "b",
			),
		),
		ydb.WithSessionPoolSizeLimit(100),
	)
	if err != nil {
		fmt.Printf("connection failed: %v", err)
	}
	defer db.Close(ctx) // cleanup resources
	fmt.Printf("connected to %s, database '%s'", db.Endpoint(), db.Name())
}

type Error 

type Error interface {
	error

	// Code reports the error code
	Code() int32

	// Name reports the short name of error
	Name() string
}

Error is an interface of error which reports about error code and error name.

func OperationError 

func OperationError(err error) Error

OperationError returns operation error description. If given err is not an operation error - returns nil.

func TransportError 

func TransportError(err error) Error

TransportError checks when given error is a transport error and returns description of transport error.

type LoggerOption 

type LoggerOption logger.Option

func WithErrWriter 

func WithErrWriter(err io.Writer) LoggerOption

func WithExternalLogger 

func WithExternalLogger(external log.Logger) LoggerOption

func WithMinLevel 

func WithMinLevel(minLevel log.Level) LoggerOption

func WithNamespace 

func WithNamespace(namespace string) LoggerOption

func WithNoColor 

func WithNoColor(b bool) LoggerOption

func WithOutWriter 

func WithOutWriter(out io.Writer) LoggerOption

type Option 

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

Option contains configuration values for Connection

func MergeOptions 

func MergeOptions(opts ...Option) Option

MergeOptions concatentaes provided options to one cumulative value.

func With 

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

With collects additional configuration options. This option does not replace collected option, instead it will append provided options.

func WithAccessTokenCredentials 

func WithAccessTokenCredentials(accessToken string) Option

func WithAnonymousCredentials 

func WithAnonymousCredentials() Option

WithAnonymousCredentials force to make requests withou authentication.

func WithBalancer 

func WithBalancer(balancer *balancerConfig.Config) Option

func WithCertificate 

func WithCertificate(cert *x509.Certificate) Option

WithCertificate appends certificate to TLS config root certificates

func WithCertificatesFromFile 

func WithCertificatesFromFile(caFile string) Option

WithCertificatesFromFile appends certificates by filepath to TLS config root certificates

func WithCertificatesFromPem 

func WithCertificatesFromPem(bytes []byte) Option

WithCertificatesFromPem appends certificates by filepath to TLS config root certificates

func WithConnectionString 

func WithConnectionString(connectionString string) Option

WithConnectionString accept connection string like 

grpc[s]://{endpoint}/?database={database}

Warning: WithConnectionString will be removed at next major release (connection string will be required string param of ydb.Open)

func WithConnectionTTL 

func WithConnectionTTL(ttl time.Duration) Option

WithConnectionTTL defines duration for parking idle connections

Warning: if defined WithSessionPoolIdleThreshold - idleThreshold must be less than connectionTTL

func WithCreateCredentialsFunc 

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

WithCreateCredentialsFunc add callback funcion to provide requests credentials

func WithCredentials 

func WithCredentials(c credentials.Credentials) Option

WithCredentials in conjunction with Connection.With function prohibit reuse of conn pool. Thus, Connection.With will effectively create totally separate Connection.

func WithDatabase 

func WithDatabase(database string) Option

WithDatabase defines database option

Warning: use WithConnectionString or dsn package instead

func WithDialTimeout 

func WithDialTimeout(timeout time.Duration) Option

WithDialTimeout sets timeout for establishing new connection to cluster

func WithDiscoveryInterval 

func WithDiscoveryInterval(discoveryInterval time.Duration) Option

WithDiscoveryInterval sets interval between cluster discovery calls.

func WithEndpoint 

func WithEndpoint(endpoint string) Option

WithEndpoint defines endpoint option

Warning: use WithConnectionString or dsn package instead

func WithInsecure 

func WithInsecure() Option

WithInsecure defines secure option.

Warning: WithInsecure lost current TLS config.

func WithLogger 

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

WithLogger add enables logging for selected tracing events.

See trace package documentation for details.

func WithMinTLSVersion 

func WithMinTLSVersion(minVersion uint16) Option

WithMinTLSVersion set minimum TLS version acceptable for connections

func WithPanicCallback 

func WithPanicCallback(panicCallback func(e interface{})) Option

WithPanicCallback specified behavior on panic Warning: WithPanicCallback must be defined on start of all options (before `WithTrace{Driver,Table,Scheme,Scripting,Coordination,Ratelimiter}` and other options) If not defined - panic would not intercept with driver

func WithRatelimiterOptions 

func WithRatelimiterOptions(opts ...ratelimiterConfig.Option) Option

WithRatelimiterOptions returns reatelimiter option

func WithRequestsType 

func WithRequestsType(requestsType string) Option

func WithSecure 

func WithSecure(secure bool) Option

WithSecure defines secure option

Warning: if secure is false - TLS config options has no effect.

func WithSessionPoolCreateSessionTimeout 

func WithSessionPoolCreateSessionTimeout(createSessionTimeout time.Duration) Option

WithSessionPoolCreateSessionTimeout set timeout for new session creation process in table.Client

func WithSessionPoolDeleteTimeout 

func WithSessionPoolDeleteTimeout(deleteTimeout time.Duration) Option

WithSessionPoolDeleteTimeout set timeout to gracefully close deleting session in table.Client

func WithSessionPoolIdleThreshold 

func WithSessionPoolIdleThreshold(idleThreshold time.Duration) Option

WithSessionPoolIdleThreshold defines keep-alive interval for idle sessions Warning: if defined WithConnectionTTL - idleThreshold must be less than connectionTTL

func WithSessionPoolKeepAliveMinSize 

func WithSessionPoolKeepAliveMinSize(keepAliveMinSize int) Option

WithSessionPoolKeepAliveMinSize set minimum sessions should be keeped alive in table.Client

func WithSessionPoolKeepAliveTimeout 

func WithSessionPoolKeepAliveTimeout(keepAliveTimeout time.Duration) Option

WithSessionPoolKeepAliveTimeout set timeout of keep alive requests for session in table.Client

func WithSessionPoolSizeLimit 

func WithSessionPoolSizeLimit(sizeLimit int) Option

WithSessionPoolSizeLimit set max size of internal sessions pool in table.Client

func WithTLSConfig 

func WithTLSConfig(tlsConfig *tls.Config) Option

WithTLSConfig replaces older TLS config

Warning: all early TLS config changes (such as WithCertificate, WithCertificatesFromFile, WithCertificatesFromPem, WithMinTLSVersion, WithTLSSInsecureSkipVerify) will be lost

func WithTLSSInsecureSkipVerify 

func WithTLSSInsecureSkipVerify() Option

WithTLSSInsecureSkipVerify applies InsecureSkipVerify flag to TLS config

func WithTableConfigOption 

func WithTableConfigOption(option tableConfig.Option) Option

WithTableConfigOption collects additional configuration options for table.Client. This option does not replace collected option, instead it will appen provided options.

func WithTraceCoordination 

func WithTraceCoordination(t trace.Coordination, opts ...trace.CoordinationComposeOption) Option

WithTraceCoordination returns coordination trace option

func WithTraceDiscovery 

func WithTraceDiscovery(t trace.Discovery, opts ...trace.DiscoveryComposeOption) Option

WithTraceDiscovery adds configured discovery tracer to Connection

func WithTraceDriver 

func WithTraceDriver(trace trace.Driver, opts ...trace.DriverComposeOption) Option

WithTraceDriver returns deadline which has associated Driver with it.

func WithTraceRatelimiter 

func WithTraceRatelimiter(t trace.Ratelimiter, opts ...trace.RatelimiterComposeOption) Option

WithTraceRatelimiter returns ratelimiter trace option

func WithTraceScheme 

func WithTraceScheme(t trace.Scheme, opts ...trace.SchemeComposeOption) Option

WithTraceScheme returns scheme trace option

func WithTraceScripting 

func WithTraceScripting(t trace.Scripting, opts ...trace.ScriptingComposeOption) Option

WithTraceScripting scripting trace option

func WithTraceTable 

func WithTraceTable(t trace.Table, opts ...trace.TableComposeOption) Option

WithTraceTable returns table trace option

func WithUserAgent 

func WithUserAgent(userAgent string) Option

WithUserAgent add provided user agent value to all api requests

Source Files

connection.go context.go doc.go errors.go logger_options.go meta.go options.go version.go with.go

Directories

PathSynopsis
balancers
config
coordination
credentials
discovery
internal
log
ratelimiter
retry
scheme
scripting
sugar
table
table/options
table/result
table/result/indexed
table/result/named
table/stats
table/types
testutil
testutil/timeutil
testutil/timeutil/timetest
trace
Version
v3.29.0
Published
Jul 18, 2022
Platform
linux/amd64
Imports
48 packages
Last checked
now –

Tools for package owners.