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

package ydb

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

Example (DatabaseSQL)

Code:play  

package main

import (
	"context"
	"database/sql"
	"log"
	"time"

	"github.com/ydb-platform/ydb-go-sdk/v3/retry"
)

func main() {
	db, err := sql.Open("ydb", "grpc://localhost:2136/local")
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = db.Close() }() // cleanup resources

	db.SetMaxOpenConns(100)
	db.SetMaxIdleConns(100)
	db.SetConnMaxIdleTime(time.Second) // workaround for background keep-aliving of YDB sessions

	var (
		id    int32  // required value
		myStr string // optional value
	)
	// retry transaction
	err = retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) error {
		row := tx.QueryRowContext(ctx, `SELECT 42 as id, "my string" as myStr`)
		if err = row.Scan(&id, &myStr); err != nil {
			return err
		}
		log.Printf("id=%v, myStr='%s'\n", id, myStr)

		return nil
	}, retry.WithIdempotent(true))
	if err != nil {
		log.Printf("query failed: %v", err)
	}
}
Example (DatabaseSQLBindAutoDeclare)

Code:play  

package main

import (
	"context"
	"database/sql"
	"log"

	"github.com/ydb-platform/ydb-go-sdk/v3/table"
	"github.com/ydb-platform/ydb-go-sdk/v3/table/types"
)

func main() {
	db, err := sql.Open("ydb",
		"grpc://localhost:2136/local?go_query_bind=declare",
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = db.Close() }() // cleanup resources

	var (
		id    int32  // required value
		title string // optional value
	)

	row := db.QueryRowContext(context.TODO(), "SELECT $id, $title",
		table.ValueParam("$id", types.Uint64Value(42)),
		table.ValueParam("$title", types.TextValue("title")),
	)
	if err = row.Scan(&id, &title); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, title='%s'\n", id, title)
	}
}
Example (DatabaseSQLBindAutoDeclareOverConnector)

Code: 

{
	var (
		ctx          = context.TODO()
		nativeDriver = ydb.MustOpen(ctx, "grpc://localhost:2136/local")
		db           = sql.OpenDB(ydb.MustConnector(nativeDriver,
			ydb.WithAutoDeclare(),
		))
	)

	row := db.QueryRowContext(context.TODO(), "SELECT $id, $title",
		table.ValueParam("$id", types.Uint64Value(42)),
		table.ValueParam("$title", types.TextValue("title")),
	)

	var (
		id    int32  // required value
		title string // optional value
	)
	if err := row.Scan(&id, &title); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, title='%s'\n", id, title)
	}
}
Example (DatabaseSQLBindNumericArgs)

Code:play  

package main

import (
	"context"
	"database/sql"
	"log"
)

func main() {
	db, err := sql.Open("ydb",
		"grpc://localhost:2136/local?go_query_bind=declare,numeric",
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = db.Close() }() // cleanup resources

	var (
		id    int32  // required value
		myStr string // optional value
	)

	// numeric args
	row := db.QueryRowContext(context.TODO(), "SELECT $2, $1", 42, "my string")
	if err = row.Scan(&myStr, &id); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, myStr='%s'\n", id, myStr)
	}
}
Example (DatabaseSQLBindNumericArgsOverConnector)

Code: 

{
	var (
		ctx          = context.TODO()
		nativeDriver = ydb.MustOpen(ctx, "grpc://localhost:2136/local")
		db           = sql.OpenDB(
			ydb.MustConnector(nativeDriver,
				ydb.WithAutoDeclare(),
				ydb.WithNumericArgs(),
			),
		)
	)
	defer nativeDriver.Close(ctx) // cleanup resources
	defer db.Close()

	// numeric args
	row := db.QueryRowContext(context.TODO(),
		"SELECT $2, $1",
		42, "my string",
	)

	var (
		id    int32  // required value
		myStr string // optional value
	)
	if err := row.Scan(&myStr, &id); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, myStr='%s'\n", id, myStr)
	}
}
Example (DatabaseSQLBindPositionalArgs)

Code:play  

package main

import (
	"context"
	"database/sql"
	"log"
)

func main() {
	db, err := sql.Open("ydb",
		"grpc://localhost:2136/local?go_query_bind=declare,positional",
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = db.Close() }() // cleanup resources

	var (
		id    int32  // required value
		myStr string // optional value
	)

	// positional args
	row := db.QueryRowContext(context.TODO(), "SELECT ?, ?", 42, "my string")
	if err = row.Scan(&id, &myStr); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, myStr='%s'\n", id, myStr)
	}
}
Example (DatabaseSQLBindPositionalArgsOverConnector)

Code: 

{
	var (
		ctx          = context.TODO()
		nativeDriver = ydb.MustOpen(ctx, "grpc://localhost:2136/local")
		db           = sql.OpenDB(
			ydb.MustConnector(nativeDriver,
				ydb.WithAutoDeclare(),
				ydb.WithNumericArgs(),
			),
		)
	)
	defer nativeDriver.Close(ctx) // cleanup resources
	defer db.Close()

	// positional args
	row := db.QueryRowContext(context.TODO(), "SELECT ?, ?", 42, "my string")

	var (
		id    int32  // required value
		myStr string // optional value
	)
	if err := row.Scan(&id, &myStr); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, myStr='%s'\n", id, myStr)
	}
}
Example (DatabaseSQLBindTablePathPrefix)

Code:play  

package main

import (
	"context"
	"database/sql"
	"log"
)

func main() {
	db, err := sql.Open("ydb",
		"grpc://localhost:2136/local?go_query_bind=table_path_prefix(/local/path/to/tables)",
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = db.Close() }() // cleanup resources

	var (
		id    int32  // required value
		title string // optional value
	)

	// full table path is "/local/path/to/tables/series"
	row := db.QueryRowContext(context.TODO(), "SELECT id, title FROM series")
	if err = row.Scan(&id, &title); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, title='%s'\n", id, title)
	}
}
Example (DatabaseSQLBindTablePathPrefixOverConnector)

Code: 

{
	var (
		ctx          = context.TODO()
		nativeDriver = ydb.MustOpen(ctx, "grpc://localhost:2136/local")
		db           = sql.OpenDB(ydb.MustConnector(nativeDriver,
			ydb.WithTablePathPrefix("/local/path/to/my/folder"),
		))
	)

	// full table path is "/local/path/to/tables/series"
	row := db.QueryRowContext(context.TODO(), "SELECT id, title FROM series")

	var (
		id    int32  // required value
		title string // optional value
	)
	if err := row.Scan(&id, &title); err != nil {
		log.Printf("query failed: %v", err)
	} else {
		log.Printf("id=%v, title='%s'\n", id, title)
	}
}
Example (Discovery)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpc://localhost:2136/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 (EnableGzipCompressionForAllRequests)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(
		ctx,
		"grpc://localhost:2135/local",
		ydb.WithAnonymousCredentials(),
		ydb.With(config.WithGrpcOptions(
			grpc.WithDefaultCallOptions(
				grpc.UseCompressor(gzip.Name),
			),
		)),
	)
	if err != nil {
		fmt.Printf("Driver failed: %v", err)
	}
	defer db.Close(ctx) // cleanup resources
	fmt.Printf("connected to %s, database '%s'", db.Endpoint(), db.Name())
}
Example (Query)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
	if err != nil {
		panic(err)
	}
	defer db.Close(ctx) // cleanup resources

	materializedResult, err := db.Query().Query( // Do retry operation on errors with best effort
		ctx, // context manage exiting from Do
		`SELECT $id as myId, $str as myStr`,
		query.WithParameters(
			ydb.ParamsBuilder().
				Param("$id").Uint64(42).
				Param("$str").Text("my string").
				Build(),
		),
		query.WithIdempotent(),
	)
	if err != nil {
		panic(err)
	}
	defer func() { _ = materializedResult.Close(ctx) }() // cleanup resources
	for rs, err := range materializedResult.ResultSets(ctx) {
		if err != nil {
			panic(err)
		}
		for row, err := range rs.Rows(ctx) {
			if err != nil {
				panic(err)
			}
			type myStruct struct {
				ID  uint64 `sql:"id"`
				Str string `sql:"myStr"`
			}
			var s myStruct
			if err = row.ScanStruct(&s); err != nil {
				panic(err)
			}
		}
	}
	if err != nil {
		panic(err)
	}
}
Example (Scripting)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpc://localhost:2136/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) { //nolint:nonamedreturns
		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"), //nolint:goerr113
				retry.WithBackoff(retry.TypeNoBackoff),
			)
		}
		if !res.NextRow() {
			return retry.RetryableError(
				fmt.Errorf("no rows"), //nolint:goerr113
				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) //nolint:goerr113
		}

		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, "grpc://localhost:2136/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
		},
		table.WithIdempotent(),
	)
	if err != nil {
		log.Printf("unexpected error: %v", err)
	}
}
Example (Topic)

Code: 

{
	ctx := context.TODO()
	db, err := ydb.Open(ctx, "grpc://localhost:2136/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 := io.ReadAll(mess)
		if err != nil {
			fmt.Printf("failed start reader: %v", err)

			return
		}
		fmt.Println(string(content))
	}
}

Index

Examples

Constants 

const (
	DataQueryMode
	ExplainQueryMode
	ScanQueryMode
	SchemeQueryMode
	ScriptingQueryMode
	QueryExecuteQueryMode
)
const Version = version.Version

Version reports current version of sdk

Functions

func GRPCConn 

func GRPCConn(cc *Driver) grpc.ClientConnInterface

GRPCConn casts *ydb.Driver 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 IsOperationErrorTransactionLocksInvalidated 

func IsOperationErrorTransactionLocksInvalidated(err error) (isTLI bool)

IsOperationErrorTransactionLocksInvalidated checks does err a TLI issue

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 ParamsBuilder 

func ParamsBuilder() params.Builder

ParamsBuilder used for create query arguments instead of tons options.

func ParamsFromMap 

func ParamsFromMap(m map[string]any, bindings ...bind.Bind) params.Parameters

ParamsFromMap build parameters from named map

Example

Code: 

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

	res, err := db.Query().QueryRow(ctx, `
		DECLARE $textArg AS Text;
		DECLARE $intArg AS Int64;
		
		SELECT $textArg AS TextField, $intArg AS IntField
		`,
		query.WithParameters(ydb.ParamsFromMap(map[string]any{
			"$textArg": "asd",
			"$intArg":  int64(123),
		})),
	)
	if err != nil {
		fmt.Printf("query failed")
	}

	var result struct {
		TextField string
		IntField  int64
	}
	err = res.ScanStruct(&result)
	if err != nil {
		fmt.Printf("scan failed")
	}
}

func RegisterDsnParser 

func RegisterDsnParser(parser func(dsn string) (opts []Option, _ error)) (registrationID int)

RegisterDsnParser registers DSN parser for ydb.Open and sql.Open driver constructors

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

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 UnregisterDsnParser 

func UnregisterDsnParser(registrationID int)

UnregisterDsnParser unregisters DSN parser by key

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

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 WithPreferredNodeID 

func WithPreferredNodeID(ctx context.Context, nodeID uint32) context.Context

WithPreferredNodeID allows to set preferred node to get session from

func WithQueryMode 

func WithQueryMode(ctx context.Context, mode QueryMode) context.Context

WithQueryMode set query mode for legacy database/sql driver

For actual database/sql driver works over query service client and no needs query mode

func WithRequestType 

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

WithRequestType returns a copy of parent context with custom request type

Deprecated: use meta.WithRequestType instead. Will be removed after Oct 2024. Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated

func WithTraceID 

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

WithTraceID returns a copy of parent context with traceID

Deprecated: use meta.WithTraceID instead. Will be removed after Oct 2024. Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated

func WithTxControl 

func WithTxControl(ctx context.Context, txControl *tx.Control) context.Context

WithTxControl modifies context for explicit define transaction control for a single query execute

Allowed the table.TransactionControl and the query.TransactionControl table.TransactionControl and query.TransactionControl are the type aliases to internal tx.Control

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
}

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

Deprecated: use Driver instance instead. Will be removed at next major release. Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated

type ConnectorOption 

type ConnectorOption = xsql.Option

func WithDatabaseSQLTrace 

func WithDatabaseSQLTrace(
	t trace.DatabaseSQL,
	opts ...trace.DatabaseSQLComposeOption,
) ConnectorOption

func WithDefaultDataQueryOptions 

func WithDefaultDataQueryOptions(opts ...options.ExecuteDataQueryOption) ConnectorOption

func WithDefaultQueryMode 

func WithDefaultQueryMode(mode QueryMode) ConnectorOption

func WithDefaultScanQueryOptions 

func WithDefaultScanQueryOptions(opts ...options.ExecuteScanQueryOption) ConnectorOption

func WithDefaultTxControl 

func WithDefaultTxControl(txControl *table.TransactionControl) ConnectorOption

func WithDisableServerBalancer 

func WithDisableServerBalancer() ConnectorOption

func WithFakeTx 

func WithFakeTx(modes ...QueryMode) ConnectorOption

func WithQueryService 

func WithQueryService(b bool) ConnectorOption

WithQueryService is an experimental flag for create database/sql driver over query service client

By default database/sql driver works over table service client Default will be changed to `WithQueryService` after March 2025

type Driver 

type Driver struct {
	// contains filtered or unexported fields
}

Driver type provide access to YDB service clients

func MustOpen 

func MustOpen(ctx context.Context, dsn string, opts ...Option) *Driver

func New 

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

New connects to database and return driver runtime holder

Deprecated: use ydb.Open instead. New func have no required arguments, such as connection string. Thats why we recognize that New have wrong signature. Will be removed after Oct 2024. Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated

func Open 

func Open(ctx context.Context, dsn string, opts ...Option) (_ *Driver, _ error)

Open connects to database by DSN and return driver runtime holder

DSN accept Driver string like 

"grpc[s]://{endpoint}/{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/local")
	if err != nil {
		fmt.Printf("Driver 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/local",
		ydb.WithAnonymousCredentials(),
		ydb.WithBalancer(
			balancers.PreferLocationsWithFallback(
				balancers.RandomChoice(), "a", "b",
			),
		),
		ydb.WithSessionPoolSizeLimit(100),
	)
	if err != nil {
		fmt.Printf("Driver failed: %v", err)
	}
	defer db.Close(ctx) // cleanup resources
	fmt.Printf("connected to %s, database '%s'", db.Endpoint(), db.Name())
}

func Unwrap 

func Unwrap[T *sql.DB | *sql.Conn](v T) (*Driver, error)

func (*Driver) Close 

func (d *Driver) Close(ctx context.Context) (finalErr error)

Close closes Driver and clear resources

func (*Driver) Coordination 

func (d *Driver) Coordination() coordination.Client

Coordination returns coordination client

func (*Driver) Discovery 

func (d *Driver) Discovery() discovery.Client

Discovery returns discovery client

func (*Driver) Endpoint 

func (d *Driver) Endpoint() string

Endpoint returns initial endpoint

func (*Driver) Name 

func (d *Driver) Name() string

Name returns database name

func (*Driver) Operation 

func (d *Driver) Operation() *operation.Client

Operation returns operation client

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

func (*Driver) Query 

func (d *Driver) Query() query.Client

Query returns query client

func (*Driver) Ratelimiter 

func (d *Driver) Ratelimiter() ratelimiter.Client

Ratelimiter returns ratelimiter client

func (*Driver) Scheme 

func (d *Driver) Scheme() scheme.Client

Scheme returns scheme client

func (*Driver) Scripting 

func (d *Driver) Scripting() scripting.Client

Scripting returns scripting client

func (*Driver) Secure 

func (d *Driver) Secure() bool

Secure returns true if database Driver is secure

func (*Driver) String 

func (d *Driver) String() string

String returns string representation of Driver

func (*Driver) Table 

func (d *Driver) Table() table.Client

Table returns table client

func (*Driver) Topic 

func (d *Driver) Topic() topic.Client

Topic returns topic client

func (*Driver) With 

func (d *Driver) With(ctx context.Context, opts ...Option) (*Driver, error)

With makes child Driver with the same options and another options

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 Option 

type Option func(ctx context.Context, d *Driver) error

Option contains configuration values for Driver

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 WithApplicationName 

func WithApplicationName(applicationName string) Option

WithApplicationName add provided application name to all api requests

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, opts ...certificates.FromFileOption) Option

WithCertificatesFromFile appends certificates by filepath to TLS config root certificates

func WithCertificatesFromPem 

func WithCertificatesFromPem(bytes []byte, opts ...certificates.FromPemOption) Option

WithCertificatesFromPem appends certificates from pem-encoded data to TLS config root certificates

func WithConnectionString 

func WithConnectionString(connectionString string) Option

WithConnectionString accept Driver string like 

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

Warning: WithConnectionString will be removed at next major release

(Driver string will be required string param of ydb.Open)

func WithConnectionTTL 

func WithConnectionTTL(ttl time.Duration) Option

WithConnectionTTL defines duration for parking idle connections

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 Driver.With function prohibit reuse of conn pool. Thus, Driver.With will effectively create totally separate Driver.

func WithDatabase 

func WithDatabase(database string) Option

WithDatabase defines database option

Warning: use ydb.Open with required Driver string parameter instead

For making Driver string from endpoint+database+secure - use sugar.DSN()

Deprecated: use dsn parameter in Open method

func WithDialTimeout 

func WithDialTimeout(timeout time.Duration) Option

WithDialTimeout sets timeout for establishing new Driver to cluster

Default dial timeout is config.DefaultDialTimeout

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 ydb.Open with required Driver string parameter instead

For making Driver string from endpoint+database+secure - use sugar.DSN()

Deprecated: use dsn parameter in Open method

func WithExecuteDataQueryOverQueryClient 

func WithExecuteDataQueryOverQueryClient(b bool) Option

WithExecuteDataQueryOverQueryClient option enables execution data queries from legacy table service client over query client API. Using this option you can execute queries from legacy table service client through `table.Session.Execute` using internal query client API without limitation of 1000 rows in response. Be careful: an OOM problem may happen because bigger result requires more memory

func WithGrpcMaxMessageSize 

func WithGrpcMaxMessageSize(sizeBytes int) Option

WithGrpcMaxMessageSize set max size of message on grpc level use the option for the driver known custom limit. Driver can't read the limit from direct grpc option

func WithIgnoreTruncated 

func WithIgnoreTruncated() Option

WithIgnoreTruncated disables errors on truncated flag

func WithInsecure 

func WithInsecure() Option

WithInsecure defines secure option.

Warning: WithInsecure lost current TLS config.

func WithLazyTx 

func WithLazyTx(lazyTx bool) Option

WithLazyTx enables lazy transactions in query service client

Lazy transaction means that begin call will be noop and first execute creates interactive transaction with given transaction settings

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

func WithLogger 

func WithLogger(l log.Logger, details trace.Detailer, opts ...log.Option) 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 WithNodeAddressMutator 

func WithNodeAddressMutator(mutator func(address string) string) Option

WithNodeAddressMutator applies mutator for node addresses from discovery.ListEndpoints response

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

func WithOauth2TokenExchangeCredentials 

func WithOauth2TokenExchangeCredentials(
	opts ...credentials.Oauth2TokenExchangeCredentialsOption,
) Option

WithOauth2TokenExchangeCredentials adds credentials that exchange token using OAuth 2.0 token exchange protocol: https://www.rfc-editor.org/rfc/rfc8693

func WithOauth2TokenExchangeCredentialsFile 

func WithOauth2TokenExchangeCredentialsFile(
	configFilePath string,
	opts ...credentials.Oauth2TokenExchangeCredentialsOption,
) Option

WithOauth2TokenExchangeCredentialsFile adds credentials that exchange token using OAuth 2.0 token exchange protocol: https://www.rfc-editor.org/rfc/rfc8693 Config file must be a valid json file

Fields of json file 

grant-type:           [string] Grant type option (default: "urn:ietf:params:oauth:grant-type:token-exchange")
res:                  [string | list of strings] Resource option (optional)
aud:                  [string | list of strings] Audience option for token exchange request (optional)
scope:                [string | list of strings] Scope option (optional)
requested-token-type: [string] Requested token type option (default: "urn:ietf:params:oauth:token-type:access_token")
subject-credentials:  [creds_json] Subject credentials options (optional)
actor-credentials:    [creds_json] Actor credentials options (optional)
token-endpoint:       [string] Token endpoint

Fields of creds_json (JWT): 

type:                 [string] Token source type. Set JWT
alg:                  [string] Algorithm for JWT signature.
							   Supported algorithms can be listed
							   with GetSupportedOauth2TokenExchangeJwtAlgorithms()
private-key:          [string] (Private) key in PEM format (RSA, EC) or Base64 format (HMAC) for JWT signature
kid:                  [string] Key id JWT standard claim (optional)
iss:                  [string] Issuer JWT standard claim (optional)
sub:                  [string] Subject JWT standard claim (optional)
aud:                  [string | list of strings] Audience JWT standard claim (optional)
jti:                  [string] JWT ID JWT standard claim (optional)
ttl:                  [string] Token TTL (default: 1h)

Fields of creds_json (FIXED): 

type:                 [string] Token source type. Set FIXED
token:                [string] Token value
token-type:           [string] Token type value. It will become
							   subject_token_type/actor_token_type parameter
							   in token exchange request (https://www.rfc-editor.org/rfc/rfc8693)

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 WithQueryConfigOption 

func WithQueryConfigOption(option queryConfig.Option) Option

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

func WithRatelimiterOptions 

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

WithRatelimiterOptions returns reatelimiter option

func WithRequestsType 

func WithRequestsType(requestsType string) Option

func WithRetryBudget 

func WithRetryBudget(b budget.Budget) Option

WithRetryBudget sets retry budget for all calls of all retryers.

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

func WithSecure 

func WithSecure(secure bool) Option

WithSecure defines secure option

Warning: use ydb.Open with required Driver string parameter instead

For making Driver string from endpoint+database+secure - use sugar.DSN()

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 interval for idle sessions

func WithSessionPoolKeepAliveMinSize 

func WithSessionPoolKeepAliveMinSize(keepAliveMinSize int) Option

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

Deprecated: use WithApplicationName instead. Will be removed after Oct 2024. Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated

func WithSessionPoolKeepAliveTimeout 

func WithSessionPoolKeepAliveTimeout(keepAliveTimeout time.Duration) Option

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

Deprecated: use WithApplicationName instead. Will be removed after Oct 2024. Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated

func WithSessionPoolSessionIdleTimeToLive 

func WithSessionPoolSessionIdleTimeToLive(idleThreshold time.Duration) Option

WithSessionPoolSessionIdleTimeToLive limits maximum time to live of idle session If idleTimeToLive is less than or equal to zero then sessions will not be closed by idle

func WithSessionPoolSessionUsageLimit 

func WithSessionPoolSessionUsageLimit[T interface{ uint64 | time.Duration }](limit T) Option

WithSessionPoolSessionUsageLimit set pool session max usage: - if argument type is uint64 - WithSessionPoolSessionUsageLimit limits max usage count of pool session - if argument type is time.Duration - WithSessionPoolSessionUsageLimit limits max time to live of pool session

func WithSessionPoolSizeLimit 

func WithSessionPoolSizeLimit(sizeLimit int) Option

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

func WithSharedBalancer 

func WithSharedBalancer(parent *Driver) Option

WithSharedBalancer sets balancer from parent driver to child driver

func WithStaticCredentials 

func WithStaticCredentials(user, password string) Option

func WithStaticCredentialsLogin 

func WithStaticCredentialsLogin(login string) Option

func WithStaticCredentialsPassword 

func WithStaticCredentialsPassword(password string) Option

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 WithTraceDatabaseSQL 

func WithTraceDatabaseSQL(t trace.DatabaseSQL, opts ...trace.DatabaseSQLComposeOption) Option

WithTraceDatabaseSQL adds configured discovery tracer to Driver

func WithTraceDiscovery 

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

WithTraceDiscovery adds configured discovery tracer to Driver

func WithTraceDriver 

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

WithTraceDriver appends trace.Driver into driver traces

func WithTraceQuery 

func WithTraceQuery(t trace.Query, opts ...trace.QueryComposeOption) Option

WithTraceQuery appends trace.Query into query traces

func WithTraceRatelimiter 

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

WithTraceRatelimiter returns ratelimiter trace option

func WithTraceRetry 

func WithTraceRetry(t trace.Retry, opts ...trace.RetryComposeOption) Option

WithTraceRetry appends trace.Retry into retry traces

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 appends trace.Table into table traces

func WithTraceTopic 

func WithTraceTopic(t trace.Topic, opts ...trace.TopicComposeOption) Option

WithTraceTopic adds configured discovery tracer to Driver

func WithUserAgent 

func WithUserAgent(userAgent string) Option

WithUserAgent add provided user agent value to all api requests

Deprecated: use WithApplicationName instead. Will be removed after Oct 2024. Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated

type Params 

type Params = params.Parameters

Params is an interface of parameters which returns from ydb.ParamsBuilder().Build()

type QueryBindConnectorOption 

type QueryBindConnectorOption interface {
	ConnectorOption
	bind.Bind
}

func WithAutoDeclare 

func WithAutoDeclare() QueryBindConnectorOption

func WithNumericArgs 

func WithNumericArgs() QueryBindConnectorOption

func WithPositionalArgs 

func WithPositionalArgs() QueryBindConnectorOption

func WithTablePathPrefix 

func WithTablePathPrefix(tablePathPrefix string) QueryBindConnectorOption

func WithWideTimeTypes 

func WithWideTimeTypes(b bool) QueryBindConnectorOption

type QueryMode 

type QueryMode int

type SQLConnector 

type SQLConnector interface {
	driver.Connector

	Close() error
}

func Connector 

func Connector(parent *Driver, opts ...ConnectorOption) (SQLConnector, error)

func MustConnector 

func MustConnector(parent *Driver, opts ...ConnectorOption) SQLConnector

Source Files

connection.go context.go driver.go driver_string.go dsn.go errors.go meta.go options.go params_builder.go params_map.go sql.go sql_unwrap.go version.go with.go

Directories

PathSynopsis
balancers
config
coordination
coordination/options
credentials
discovery
internal
log
meta
metrics
operation
query
ratelimiter
retry
retry/budget
scheme
scripting
spans
sugar
table
table/options
table/result
table/result/indexed
table/result/named
table/stats
table/types
testutil
topic
topic/topiclistener
topic/topicoptions
topic/topicreaderPackage topicreader provide Reader to receive messages from YDB topics More examples in examples repository
topic/topicsugar
topic/topictypes
topic/topicwriter
trace
Version
v3.108.0 (latest)
Published
Apr 21, 2025
Platform
js/wasm
Imports
73 packages
Last checked
1 second ago –

Tools for package owners.