ydb

package module
v3.21.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2022 License: Apache-2.0 Imports: 42 Imported by: 86

README

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

PkgGoDev tests lint Go Report Card codecov Code lines Comments

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 Usage

  • connect to YDB 
    db, err := ydb.Open(ctx, "grpcs://localhost:2135/?database=/local", ydb.WithAnonymousCredentials())
if err != nil {
    log.Fatal(err)
}
  • execute SELECT query 
    const query = `SELECT 42 as id, "myStr" as myStr;`

// Do retry operation on errors with best effort
queryErr := db.Table().Do(ctx, func(ctx context.Context, s table.Session) (err error) {
    _, res, err := s.Execute(ctx, table.DefaultTxControl(), query, nil)
    if err != nil {
        return err
    }
    defer res.Close()
    if err = res.NextResultSetErr(ctx); err != nil {
        return err 
    }
    for res.NextRow() {
        var id    int32   
        var myStr string 
        err = res.ScanNamed(named.Required("id", &id),named.OptionalWithDefault("myStr", &myStr))
        if err != nil {
            log.Fatal(err)
        }
		log.Printf("id=%v, myStr='%s'\n", id, myStr)
    }
    return res.Err() // for driver retry if not nil
})
if queryErr != nil {
    log.Fatal(queryErr)
}

More examples of usage placed in examples repository.

Credentials

Driver contains two options for making simple credentials.Credentials:

  • ydb.WithAnonymousCredentials()
  • ydb.WithAccessTokenCredentials("token")

Another variants of credentials.Credentials object provides with external packages:

Package Type Description Link of example usage
ydb-go-yc credentials credentials provider for Yandex.Cloud yc.WithServiceAccountKeyFileCredentials
yc.WithInternalCA yc.WithMetadataCredentials
ydb-go-yc-metadata credentials metadata credentials provider for Yandex.Cloud yc.WithInternalCA yc.WithCredentials
ydb-go-sdk-auth-environ credentials create credentials from environ ydbEnviron.WithEnvironCredentials

Ecosystem of debug tools over ydb-go-sdk

Package ydb-go-sdk provide debugging over trace events in package trace. Next packages provide debug tooling:

Package Type Description Link of example usage
ydb-go-sdk-zap logging logging ydb-go-sdk events with zap package ydbZap.WithTraces
ydb-go-sdk-zerolog logging logging ydb-go-sdk events with zerolog package ydbZerolog.WithTraces
ydb-go-sdk-metrics metrics common metrics of ydb-go-sdk. Package declare interfaces such as Registry, GaugeVec and Gauge and use it for traces
ydb-go-sdk-prometheus metrics prometheus wrapper over ydb-go-sdk-metrics ydbPrometheus.WithTraces
ydb-go-sdk-opentracing tracing opentracing plugin for trace internal ydb-go-sdk calls ydbOpentracing.WithTraces

Environment variables

ydb-go-sdk supports next environment variables which redefines default behavior of driver

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

Documentation

Overview

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 (TableBulkUpsert) 
ctx := context.Background()
db, err := ydb.Open(ctx,
	"grpcs://localhost:2135/?database=/local",
	ydb.WithAnonymousCredentials(),
)
if err != nil {
	log.Fatal(err)
}
defer func() {
	_ = db.Close(ctx)
}()
type logMessage struct {
	App       string
	Host      string
	Timestamp time.Time
	HTTPCode  uint32
	Message   string
}
// prepare native go data
const batchSize = 10000
logs := make([]logMessage, 0, batchSize)
for i := 0; i < batchSize; i++ {
	message := logMessage{
		App:       fmt.Sprintf("App_%d", i/256),
		Host:      fmt.Sprintf("192.168.0.%d", i%256),
		Timestamp: time.Now().Add(time.Millisecond * time.Duration(i%1000)),
		HTTPCode:  200,
	}
	if i%2 == 0 {
		message.Message = "GET / HTTP/1.1"
	} else {
		message.Message = "GET /images/logo.png HTTP/1.1"
	}
	logs = append(logs, message)
}
// execute bulk upsert with native ydb data
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
		rows := make([]types.Value, 0, len(logs))
		for _, msg := range logs {
			rows = append(rows, types.StructValue(
				types.StructFieldValue("App", types.UTF8Value(msg.App)),
				types.StructFieldValue("Host", types.UTF8Value(msg.Host)),
				types.StructFieldValue("Timestamp", types.TimestampValueFromTime(msg.Timestamp)),
				types.StructFieldValue("HTTPCode", types.Uint32Value(msg.HTTPCode)),
				types.StructFieldValue("Message", types.UTF8Value(msg.Message)),
			))
		}
		return s.BulkUpsert(ctx, "/local/bulk_upsert_example", types.ListValue(rows...))
	},
)
if err != nil {
	log.Printf("unexpected error: %v", err)
}

Output:
Example (TableCreateTable) 
ctx := context.Background()
db, err := ydb.Open(ctx,
	"grpcs://localhost:2135/?database=/local",
	ydb.WithAnonymousCredentials(),
)
if err != nil {
	log.Fatal(err)
}
defer func() {
	_ = db.Close(ctx)
}()
err = db.Table().Do(
	ctx,
	func(ctx context.Context, s table.Session) (err error) {
		return s.CreateTable(ctx, path.Join(db.Name(), "series"),
			options.WithColumn("series_id", types.Optional(types.TypeUint64)),
			options.WithColumn("title", types.Optional(types.TypeUTF8)),
			options.WithColumn("series_info", types.Optional(types.TypeUTF8)),
			options.WithColumn("release_date", types.Optional(types.TypeDate)),
			options.WithColumn("comment", types.Optional(types.TypeUTF8)),
			options.WithPrimaryKeyColumn("series_id"),
		)
	},
)
if err != nil {
	log.Printf("unexpected error: %v", err)
}

Output:
Example (TableSelect) 
ctx := context.Background()
db, err := ydb.Open(ctx,
	"grpcs://localhost:2135/?database=/local",
	ydb.WithAnonymousCredentials(),
)
if err != nil {
	log.Fatal(err)
}
defer func() {
	_ = db.Close(ctx)
}()
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 driver retry
		}
		defer func() {
			_ = res.Close() // must close always
		}()
		if err = res.NextResultSetErr(ctx); err != nil { // check single result set and switch to it
			return err // for driver retry
		}
		for res.NextRow() { // iterate over rows
			err = res.ScanNamed(
				named.Required("id", &id),
				named.OptionalWithDefault("myStr", &myStr),
			)
			if err != nil {
				return err
			}
			log.Printf("id=%v, myStr='%s'\n", id, myStr)
		}
		return res.Err() // for driver retry if not nil
	},
)
if err != nil {
	log.Printf("unexpected error: %v", err)
}

Output:

Index

Examples

Constants

View Source 
const Version = meta.Version

Version reports current version of sdk

Variables

This section is empty.

Functions

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 added in v3.5.0 

func IsOperationErrorAlreadyExistsError(err error) bool

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

func IsOperationErrorNotFoundError added in v3.5.0 

func IsOperationErrorNotFoundError(err error) bool

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

func IsOperationErrorOverloaded added in v3.5.0 

func IsOperationErrorOverloaded(err error) bool

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

func IsOperationErrorSchemeError added in v3.5.0 

func IsOperationErrorSchemeError(err error) bool

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

func IsOperationErrorUnavailable added in v3.5.0 

func IsOperationErrorUnavailable(err error) bool

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

func IsRatelimiterAcquireError added in v3.11.0 

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 added in v3.4.2 

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 added in v3.11.0 

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 added in v3.18.0 

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 added in v3.18.0 

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 added in v3.13.0 

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

WithRequestType returns a copy of parent context with custom request type

func WithTraceID added in v3.13.0 

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

WithTraceID returns a copy of parent context with traceID

Types

type Connection 

type Connection interface {
	grpc.ClientConnInterface

	// Endpoint returns initial endpoint
	Endpoint() string

	// Name returns database name
	Name() string

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

	Close(ctx context.Context) error

	// Method for accessing subsystems
	Table() table.Client
	Scheme() scheme.Client
	Coordination() coordination.Client
	Ratelimiter() ratelimiter.Client
	Discovery() discovery.Client
	Scripting() scripting.Client

	// Make copy with additional 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 deprecated 

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 added in v3.21.0 

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}"

type Error added in v3.4.2 

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 added in v3.16.9 

func OperationError(err error) Error

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

func TransportError added in v3.16.9 

func TransportError(err error) Error

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

type LoggerOption added in v3.5.3 

type LoggerOption logger.Option

func WithErrWriter added in v3.5.0 

func WithErrWriter(err io.Writer) LoggerOption

func WithExternalLogger added in v3.5.0 

func WithExternalLogger(external log.Logger) LoggerOption

func WithMinLevel added in v3.3.0 

func WithMinLevel(minLevel log.Level) LoggerOption

func WithNamespace added in v3.3.0 

func WithNamespace(namespace string) LoggerOption

func WithNoColor added in v3.3.0 

func WithNoColor(b bool) LoggerOption

func WithOutWriter added in v3.5.0 

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 added in v3.5.1 

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 appen provided options.

func WithAccessTokenCredentials 

func WithAccessTokenCredentials(accessToken string) Option

func WithAnonymousCredentials 

func WithAnonymousCredentials() Option

WithAnonymousCredentials force to make requests withou authentication.

func WithBalancer added in v3.6.0 

func WithBalancer(balancer balancer.Balancer) Option

func WithCertificate 

func WithCertificate(cert *x509.Certificate) Option

WithCertificate provides custom CA certificate.

func WithCertificatesFromFile 

func WithCertificatesFromFile(caFile string) Option

WithCertificate provides filepath to load custom CA certificates.

func WithCertificatesFromPem 

func WithCertificatesFromPem(bytes []byte) Option

WithCertificate provides PEM encoded custom CA 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 added in v3.7.0 

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 deprecated added in v3.2.1 

func WithDatabase(database string) Option

WithDatabase defines database option

Deprecated: 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 deprecated added in v3.2.1 

func WithEndpoint(endpoint string) Option

WithEndpoint defines endpoint option

Deprecated: use WithConnectionString or dsn package instead

func WithInsecure deprecated added in v3.8.6 

func WithInsecure() Option

WithInsecure defines secure option

Deprecated: use WithConnectionString or dsn package instead

func WithLogger added in v3.3.0 

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

WithLogger add enables logging for selected tracing events. See trace package documentation for details.

func WithMinTLSVersion added in v3.9.1 

func WithMinTLSVersion(minVersion uint16) Option

WithMinTLSVersion set minimum TLS version acceptable for connections

func WithPanicCallback added in v3.17.0 

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 added in v3.11.0 

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

WithRatelimiterOptions returns reatelimiter option

func WithRequestsType added in v3.13.0 

func WithRequestsType(requestsType string) Option

func WithSecure deprecated added in v3.7.0 

func WithSecure(secure bool) Option

WithSecure defines secure option

Deprecated: use WithConnectionString or dsn package instead

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 WithTLSSInsecureSkipVerify added in v3.11.0 

func WithTLSSInsecureSkipVerify() Option

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 added in v3.10.0 

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

WithTraceCoordination returns coordination trace option

func WithTraceDiscovery added in v3.10.0 

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 added in v3.10.0 

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

WithTraceRatelimiter returns ratelimiter trace option

func WithTraceScheme added in v3.10.0 

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

WithTraceScheme returns scheme trace option

func WithTraceScripting added in v3.10.0 

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 added in v3.7.0 

func WithUserAgent(userAgent string) Option

WithUserAgent add provided user agent value to all api requests

Source Files

View all Source files

Directories

Path Synopsis
internal
backoff
balancer
balancer/list
balancer/multi
balancer/rr
balancer/single
balancer/stub
closer
cluster
cluster/entry
cmd/gtrace
config
conn
coordination
coordination/config
credentials
database
deadline
decimal
Package decimal provides tools for working with YDB's decimal types.
 Package decimal provides tools for working with YDB's decimal types.
discovery
discovery/config
dsn
endpoint
feature
lazy
logger
logger/level
meta
operation
ratelimiter
ratelimiter/config
ratelimiter/errors
ratelimiter/options
repeater
response
retry
scheme
scheme/config
scripting
scripting/config
table
table/config
table/scanner
timeutil
value
wait
wrap
xerrors
xnet
xrand
xresolver
options
result
result/indexed
result/named
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.