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 (Discovery) ¶
ctx := context.TODO() db, err := ydb.Open(ctx, "grpcs://localhost:2135/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()) }
Output:
Example (Scripting) ¶
ctx := context.TODO() db, err := ydb.Open(ctx, "grpcs://localhost:2135/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) }
Output:
Example (Table) ¶
ctx := context.TODO() db, err := ydb.Open(ctx, "grpcs://localhost:2135/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) }
Output:
Example (Topic) ¶
ctx := context.TODO() db, err := ydb.Open(ctx, "grpcs://localhost:2135/?database=/local") if err != nil { fmt.Printf("failed connect: %v", err) return } defer db.Close(ctx) // cleanup resources reader, err := db.Topic().StartReader("consumer", topicoptions.ReadTopic("/topic/path")) if err != nil { fmt.Printf("failed start reader: %v", err) return } for { mess, err := reader.ReadMessage(ctx) if err != nil { fmt.Printf("failed start reader: %v", err) return } content, err := ioutil.ReadAll(mess) if err != nil { fmt.Printf("failed start reader: %v", err) return } fmt.Println(string(content)) }
Output:
Index ¶
- Constants
- func Connector(db Connection, opts ...ConnectorOption) (*xsql.Connector, error)
- func GRPCConn(conn Connection) grpc.ClientConnInterface
- func IsOperationError(err error, codes ...Ydb.StatusIds_StatusCode) bool
- func IsOperationErrorAlreadyExistsError(err error) bool
- func IsOperationErrorNotFoundError(err error) bool
- func IsOperationErrorOverloaded(err error) bool
- func IsOperationErrorSchemeError(err error) bool
- func IsOperationErrorUnavailable(err error) bool
- func IsRatelimiterAcquireError(err error) bool
- func IsTimeoutError(err error) bool
- func IsTransportError(err error, codes ...grpcCodes.Code) bool
- func IsYdbError(err error) bool
- func IterateByIssues(err error, ...)
- func ToRatelimiterAcquireError(err error) ratelimiter.AcquireError
- func WithOperationCancelAfter(ctx context.Context, operationCancelAfter time.Duration) context.Context
- func WithOperationTimeout(ctx context.Context, operationTimeout time.Duration) context.Context
- func WithQueryMode(ctx context.Context, mode QueryMode) context.Context
- func WithRequestType(ctx context.Context, requestType string) context.Context
- func WithTraceID(ctx context.Context, traceID string) context.Context
- type Connection
- type ConnectorOption
- func WithDefaultDataQueryOptions(opts ...options.ExecuteDataQueryOption) ConnectorOption
- func WithDefaultQueryMode(mode QueryMode) ConnectorOption
- func WithDefaultScanQueryOptions(opts ...options.ExecuteScanQueryOption) ConnectorOption
- func WithDefaultTxControl(txControl *table.TransactionControl) ConnectorOption
- type Error
- type LoggerOption
- type Option
- func MergeOptions(opts ...Option) Option
- func With(options ...config.Option) Option
- func WithAccessTokenCredentials(accessToken string) Option
- func WithAnonymousCredentials() Option
- func WithBalancer(balancer *balancerConfig.Config) Option
- func WithCertificate(cert *x509.Certificate) Option
- func WithCertificatesFromFile(caFile string) Option
- func WithCertificatesFromPem(bytes []byte) Option
- func WithConnectionString(connectionString string) Option
- func WithConnectionTTL(ttl time.Duration) Option
- func WithCreateCredentialsFunc(createCredentials func(ctx context.Context) (credentials.Credentials, error)) Option
- func WithCredentials(c credentials.Credentials) Option
- func WithDatabase(database string) Option
- func WithDialTimeout(timeout time.Duration) Option
- func WithDiscoveryInterval(discoveryInterval time.Duration) Option
- func WithEndpoint(endpoint string) Option
- func WithInsecure() Option
- func WithLogger(details trace.Details, opts ...LoggerOption) Option
- func WithMinTLSVersion(minVersion uint16) Option
- func WithPanicCallback(panicCallback func(e interface{})) Option
- func WithRatelimiterOptions(opts ...ratelimiterConfig.Option) Option
- func WithRequestsType(requestsType string) Option
- func WithSecure(secure bool) 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 WithTLSConfig(tlsConfig *tls.Config) Option
- func WithTLSSInsecureSkipVerify() Option
- func WithTableConfigOption(option tableConfig.Option) Option
- func WithTraceCoordination(t trace.Coordination, opts ...trace.CoordinationComposeOption) Option
- func WithTraceDiscovery(t trace.Discovery, opts ...trace.DiscoveryComposeOption) Option
- func WithTraceDriver(trace trace.Driver, opts ...trace.DriverComposeOption) Option
- func WithTraceRatelimiter(t trace.Ratelimiter, opts ...trace.RatelimiterComposeOption) Option
- func WithTraceScheme(t trace.Scheme, opts ...trace.SchemeComposeOption) Option
- func WithTraceScripting(t trace.Scripting, opts ...trace.ScriptingComposeOption) Option
- func WithTraceTable(t trace.Table, opts ...trace.TableComposeOption) Option
- func WithTraceTopic(t trace.Topic, opts ...trace.DiscoveryComposeOption) Option
- func WithUserAgent(userAgent string) Option
- type QueryMode
Examples ¶
Constants ¶
const ( DataQueryMode = xsql.DataQueryMode ExplainQueryMode = xsql.ExplainQueryMode ScanQueryMode = xsql.ScanQueryMode SchemeQueryMode = xsql.SchemeQueryMode ScriptingQueryMode = xsql.ScriptingQueryMode )
const Version = meta.Version
Version reports current version of sdk
Variables ¶
This section is empty.
Functions ¶
func Connector ¶ added in v3.33.0
func Connector(db Connection, opts ...ConnectorOption) (*xsql.Connector, error)
func GRPCConn ¶ added in v3.25.0
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 ¶ added in v3.5.0
IsOperationErrorAlreadyExistsError checks whether given err is an operation error with code AlreadyExistsError
func IsOperationErrorNotFoundError ¶ added in v3.5.0
IsOperationErrorNotFoundError checks whether given err is an operation error with code NotFoundError
func IsOperationErrorOverloaded ¶ added in v3.5.0
IsOperationErrorOverloaded checks whether given err is an operation error with code Overloaded
func IsOperationErrorSchemeError ¶ added in v3.5.0
IsOperationErrorSchemeError checks whether given err is an operation error with code SchemeError
func IsOperationErrorUnavailable ¶ added in v3.5.0
IsOperationErrorUnavailable checks whether given err is an operation error with code Unavailable
func IsRatelimiterAcquireError ¶ added in v3.11.0
IsRatelimiterAcquireError checks whether given err is an ratelimiter acquire error
func IsTimeoutError ¶
IsTimeoutError checks whether given err is a some timeout error (context, transport or operation).
func IsTransportError ¶
IsTransportError checks whether given err is a transport (grpc) error.
func IsYdbError ¶ added in v3.4.2
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
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 WithQueryMode ¶ added in v3.33.0
func WithRequestType ¶ added in v3.13.0
WithRequestType returns a copy of parent context with custom request type
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 // Topic returns topic client Topic() topic.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 Open ¶ added in v3.21.0
Open connects to database by DSN and return driver runtime holder
DSN accept connection string like
"grpc[s]://{endpoint}/?database={database}[¶m=value]"
See sugar.DSN helper for make dsn from endpoint and database
Example ¶
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())
Output:
Example (Advanced) ¶
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())
Output:
type ConnectorOption ¶ added in v3.33.0
type ConnectorOption = xsql.ConnectorOption
func WithDefaultDataQueryOptions ¶ added in v3.33.0
func WithDefaultDataQueryOptions(opts ...options.ExecuteDataQueryOption) ConnectorOption
func WithDefaultQueryMode ¶ added in v3.33.0
func WithDefaultQueryMode(mode QueryMode) ConnectorOption
func WithDefaultScanQueryOptions ¶ added in v3.33.0
func WithDefaultScanQueryOptions(opts ...options.ExecuteScanQueryOption) ConnectorOption
func WithDefaultTxControl ¶ added in v3.33.0
func WithDefaultTxControl(txControl *table.TransactionControl) ConnectorOption
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
OperationError returns operation error description. If given err is not an operation error - returns nil.
func TransportError ¶ added in v3.16.9
TransportError checks when given error is a transport error and returns description of transport error.
type LoggerOption ¶ added in v3.5.3
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 ¶
Option contains configuration values for Connection
func MergeOptions ¶ added in v3.5.1
MergeOptions concatentaes provided options to one cumulative value.
func With ¶
With collects additional configuration options. This option does not replace collected option, instead it will append provided options.
func WithAnonymousCredentials ¶
func WithAnonymousCredentials() Option
WithAnonymousCredentials force to make requests withou authentication.
func WithBalancer ¶ added in v3.6.0
func WithBalancer(balancer *balancerConfig.Config) Option
func WithCertificate ¶
func WithCertificate(cert *x509.Certificate) Option
WithCertificate appends certificate to TLS config root certificates
func WithCertificatesFromFile ¶
WithCertificatesFromFile appends certificates by filepath to TLS config root certificates
func WithCertificatesFromPem ¶
WithCertificatesFromPem appends certificates by filepath to TLS config root certificates
func WithConnectionString ¶
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
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 ¶ added in v3.2.1
WithDatabase defines database option
Warning: use WithConnectionString or dsn package instead
func WithDialTimeout ¶
WithDialTimeout sets timeout for establishing new connection to cluster
func WithDiscoveryInterval ¶
WithDiscoveryInterval sets interval between cluster discovery calls.
func WithEndpoint ¶ added in v3.2.1
WithEndpoint defines endpoint option
Warning: use WithConnectionString or dsn package instead
func WithInsecure ¶ added in v3.8.6
func WithInsecure() Option
WithInsecure defines secure option.
Warning: WithInsecure lost current TLS config.
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
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 WithSecure ¶ added in v3.7.0
WithSecure defines secure option
Warning: if secure is false - TLS config options has no effect.
func WithSessionPoolCreateSessionTimeout ¶
WithSessionPoolCreateSessionTimeout set timeout for new session creation process in table.Client
func WithSessionPoolDeleteTimeout ¶
WithSessionPoolDeleteTimeout set timeout to gracefully close deleting session in table.Client
func WithSessionPoolIdleThreshold ¶
WithSessionPoolIdleThreshold defines keep-alive interval for idle sessions Warning: if defined WithConnectionTTL - idleThreshold must be less than connectionTTL
func WithSessionPoolKeepAliveMinSize ¶
WithSessionPoolKeepAliveMinSize set minimum sessions should be keeped alive in table.Client
func WithSessionPoolKeepAliveTimeout ¶
WithSessionPoolKeepAliveTimeout set timeout of keep alive requests for session in table.Client
func WithSessionPoolSizeLimit ¶
WithSessionPoolSizeLimit set max size of internal sessions pool in table.Client
func WithTLSConfig ¶ added in v3.23.0
WithTLSConfig replaces older TLS config
Warning: all early TLS config changes (such as WithCertificate, WithCertificatesFromFile, WithCertificatesFromPem, WithMinTLSVersion, WithTLSSInsecureSkipVerify) will be lost
func WithTLSSInsecureSkipVerify ¶ added in v3.11.0
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 ¶ 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 WithTraceTopic ¶ added in v3.32.0
func WithTraceTopic(t trace.Topic, opts ...trace.DiscoveryComposeOption) Option
WithTraceTopic adds configured discovery tracer to Connection
func WithUserAgent ¶ added in v3.7.0
WithUserAgent add provided user agent value to all api requests
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
internal
|
|
topicreader
Package topicreader provide Reader to receive messages from YDB topics More examples in examples repository
|
Package topicreader provide Reader to receive messages from YDB topics More examples in examples repository |