ydb

package module
v3.78.0 Latest Latest
Warning

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

 Go to latest Published: Sep 4, 2024 License: Apache-2.0 Imports: 67 Imported by: 86

README ¶

ydb-go-sdk - pure Go native and database/sql driver for YDB

License Release PkgGoDev tests lint Go Report Card codecov Code lines View examples Telegram WebSite PRs Welcome

Supports discovery, operation, table, query, coordination, ratelimiter, scheme, scripting and topic clients for YDB. YDB is an open-source Distributed SQL Database that combines high availability and scalability with strict consistency and ACID transactions. YDB was created primarily for OLTP workloads and supports some OLAP scenarious.

Supported Go Versions

ydb-go-sdk supports all Go versions supported by the official Go Release Policy. That is, the latest two versions of Go (or more, but with no guarantees for extra versions).

Versioning Policy

ydb-go-sdk comply to guidelines from SemVer2.0.0 with an several exceptions.

Installation

go get -u github.com/ydb-platform/ydb-go-sdk/v3

Example Usage

  • connect to YDB
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
    log.Fatal(err)
}
  • execute SELECT query over Table service client
// Do retry operation on errors with best effort
err := db.Table().Do(ctx, func(ctx context.Context, s table.Session) (err error) {
   _, res, err := s.Execute(ctx, table.DefaultTxControl(), 
   	`SELECT 42 as id, "myStr" as myStr;`, 
   	nil, // empty parameters
   )
   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 err != nil {
   log.Fatal(err)
}
  • execute SELECT query over Query service client
// Do retry operation on errors with best effort
err := db.Query().Do( // Do retry operation on errors with best effort
   ctx, // context manage exiting from Do
   func(ctx context.Context, s query.Session) (err error) { // retry operation
   	streamResult, err := s.Query(ctx, `SELECT 42 as id, "myStr" as myStr;`))
   	if err != nil {
   		return err // for auto-retry with driver
   	}
   	defer func() { _ = streamResult.Close(ctx) }() // cleanup resources
   	for s, err := range streamResult.ResultSets(ctx) {
   		if err != nil {
   			return err
   		}
   		for row, err := range rs.Rows(ctx) {
   			if err != nil {
   				return err
   			}
   			type myStruct struct {
   				id  uint64 `sql:"id"`
   				str string `sql:"myStr"`
   			}
   			var s myStruct
   			if err = row.ScanStruct(&s); err != nil {
   				return err // generally scan error not retryable, return it for driver check error
   			}
   		}
   	}

   	return nil
   },
   query.WithIdempotent(),
)
if err != nil {
   log.Fatal(err)
}
  • usage with database/sql (see additional docs in SQL.md )
import (
    "context"
    "database/sql"
    "log"

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

...

db, err := sql.Open("ydb", "grpc://localhost:2136/local")
if err != nil {
    log.Fatal(err)
}
defer db.Close() // cleanup resources
var (
    id    int32
    myStr string
)
row := db.QueryRowContext(context.TODO(), `SELECT 42 as id, "my string" as myStr`)
if err = row.Scan(&id, &myStr); err != nil {
    log.Printf("select failed: %v", err)
    return
}
log.Printf("id = %d, myStr = \"%s\"", id, myStr)

More examples of usage placed in examples directory.

Credentials

Driver implements several ways for making credentials for YDB:

  • ydb.WithAnonymousCredentials() (enabled by default unless otherwise specified)
  • ydb.WithAccessTokenCredentials("token")
  • ydb.WithStaticCredentials("user", "password"),
  • as part of connection string, like as grpcs://user:password@endpoint/database

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-logrus logging logging ydb-go-sdk events with logrus package ydbLogrus.WithTraces
ydb-go-sdk-prometheus metrics prometheus wrapper over ydb-go-sdk/v3/metrics ydbPrometheus.WithTraces
ydb-go-sdk-opentracing tracing OpenTracing plugin for trace internal ydb-go-sdk calls ydbOpentracing.WithTraces
ydb-go-sdk-otel tracing OpenTelemetry plugin for trace internal ydb-go-sdk calls ydbOtel.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_DETAILS string .* regexp for lookup internal logger logs
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 ¶

Example (DatabaseSQL) ¶ 
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)
	}
}

Output:
Example (DatabaseSQLBindAutoDeclare) ¶ 
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)
	}
}

Output:
Example (DatabaseSQLBindAutoDeclareOverConnector) ¶ 
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)
}

Output:
Example (DatabaseSQLBindNumericArgs) ¶ 
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)
	}
}

Output:
Example (DatabaseSQLBindNumericArgsOverConnector) ¶ 
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)
}

Output:
Example (DatabaseSQLBindPositionalArgs) ¶ 
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)
	}
}

Output:
Example (DatabaseSQLBindPositionalArgsOverConnector) ¶ 
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)
}

Output:
Example (DatabaseSQLBindTablePathPrefix) ¶ 
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)
	}
}

Output:
Example (DatabaseSQLBindTablePathPrefixOverConnector) ¶ 
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)
}

Output:
Example (Discovery) ¶ 
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())
}

Output:
Example (EnableGzipCompressionForAllRequests) ¶ 
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())

Output:
Example (Query) ¶ 
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)
}

Output:
Example (Scripting) ¶ 
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)
}

Output:
Example (Table) ¶ 
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)
}

Output:
Example (Topic) ¶ 
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))
}

Output:

Index ¶

Examples ¶

Constants ¶

View Source 
const (
	DataQueryMode      = xsql.DataQueryMode
	ExplainQueryMode   = xsql.ExplainQueryMode
	ScanQueryMode      = xsql.ScanQueryMode
	SchemeQueryMode    = xsql.SchemeQueryMode
	ScriptingQueryMode = xsql.ScriptingQueryMode
)
View Source 
const Version = version.Version

Version reports current version of sdk

Variables ¶

This section is empty.

Functions ¶

func GRPCConn ¶ added in v3.25.0 

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 ¶ 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 IsOperationErrorTransactionLocksInvalidated ¶ added in v3.48.4 

func IsOperationErrorTransactionLocksInvalidated(err error) (isTLI bool)

IsOperationErrorTransactionLocksInvalidated checks does err a TLI issue

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 ParamsBuilder ¶ added in v3.57.0 

func ParamsBuilder() params.Builder

ParamsBuilder used for create query arguments instead of tons options.

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

func RegisterDsnParser ¶ added in v3.68.0 

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 ¶ 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 UnregisterDsnParser ¶ added in v3.68.0 

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 ¶ 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 WithQueryMode ¶ added in v3.33.0 

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

func WithRequestType deprecated 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

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

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

func WithTxControl(ctx context.Context, txc *table.TransactionControl) context.Context

Types ¶

type Connection deprecated 

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

type ConnectorOption = xsql.ConnectorOption

func WithDatabaseSQLTrace ¶ added in v3.34.0 

func WithDatabaseSQLTrace(
	t trace.DatabaseSQL,
	opts ...trace.DatabaseSQLComposeOption,
) 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

func WithDisableServerBalancer ¶ added in v3.42.4 

func WithDisableServerBalancer() ConnectorOption

func WithFakeTx ¶ added in v3.44.0 

func WithFakeTx(mode QueryMode) ConnectorOption

type Driver ¶ added in v3.43.0 

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

Driver type provide access to YDB service clients

func MustOpen ¶ added in v3.44.0 

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

func New deprecated 

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

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 ¶ 
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())

Output:
Example (Advanced) ¶ 
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())

Output:

func Unwrap ¶ added in v3.33.0 

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

func (*Driver) Close ¶ added in v3.43.0 

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

Close closes Driver and clear resources

func (*Driver) Coordination ¶ added in v3.43.0 

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

Coordination returns coordination client

func (*Driver) Discovery ¶ added in v3.43.0 

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

Discovery returns discovery client

func (*Driver) Endpoint ¶ added in v3.43.0 

func (d *Driver) Endpoint() string

Endpoint returns initial endpoint

func (*Driver) Name ¶ added in v3.43.0 

func (d *Driver) Name() string

Name returns database name

func (*Driver) Operation ¶ added in v3.77.0 

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

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

Query returns query client

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

func (*Driver) Ratelimiter ¶ added in v3.43.0 

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

Ratelimiter returns ratelimiter client

func (*Driver) Scheme ¶ added in v3.43.0 

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

Scheme returns scheme client

func (*Driver) Scripting ¶ added in v3.43.0 

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

Scripting returns scripting client

func (*Driver) Secure ¶ added in v3.43.0 

func (d *Driver) Secure() bool

Secure returns true if database Driver is secure

func (*Driver) String ¶ added in v3.54.3 

func (d *Driver) String() string

String returns string representation of Driver

func (*Driver) Table ¶ added in v3.43.0 

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

Table returns table client

func (*Driver) Topic ¶ added in v3.43.0 

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

Topic returns topic client

func (*Driver) With ¶ added in v3.43.0 

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

With makes child Driver with the same options and another options

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 Option ¶ 

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

Option contains configuration values for Driver

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

func WithAccessTokenCredentials ¶ 

func WithAccessTokenCredentials(accessToken string) Option

func WithAnonymousCredentials ¶ 

func WithAnonymousCredentials() Option

WithAnonymousCredentials force to make requests withou authentication.

func WithApplicationName ¶ added in v3.57.4 

func WithApplicationName(applicationName string) Option

WithApplicationName add provided application name to all api requests

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 ¶ 

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

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

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()

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

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()

func WithIgnoreTruncated ¶ added in v3.36.0 

func WithIgnoreTruncated() Option

WithIgnoreTruncated disables errors on truncated flag

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(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 ¶ added in v3.9.1 

func WithMinTLSVersion(minVersion uint16) Option

WithMinTLSVersion set minimum TLS version acceptable for connections

func WithNodeAddressMutator ¶ added in v3.67.0 

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

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

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 ¶ 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 WithQueryConfigOption ¶ added in v3.57.0 

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 ¶ 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 WithRetryBudget ¶ added in v3.66.0 

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

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 deprecated 

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 deprecated 

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 WithSessionPoolSizeLimit ¶ 

func WithSessionPoolSizeLimit(sizeLimit int) Option

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

func WithStaticCredentials ¶ added in v3.34.0 

func WithStaticCredentials(user, password string) Option

func WithTLSConfig ¶ added in v3.23.0 

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 ¶ 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 WithTraceDatabaseSQL ¶ added in v3.34.0 

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

WithTraceDatabaseSQL adds configured discovery tracer to Driver

func WithTraceDiscovery ¶ added in v3.10.0 

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

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

WithTraceQuery appends trace.Query into query traces

func WithTraceRatelimiter ¶ added in v3.10.0 

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

WithTraceRatelimiter returns ratelimiter trace option

func WithTraceRetry ¶ added in v3.54.0 

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

WithTraceRetry appends trace.Retry into retry traces

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

func WithTraceTopic ¶ added in v3.32.0 

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

WithTraceTopic adds configured discovery tracer to Driver

func WithUserAgent deprecated added in v3.7.0 

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 QueryBindConnectorOption ¶ added in v3.44.0 

type QueryBindConnectorOption interface {
	ConnectorOption
	bind.Bind
}

func WithAutoDeclare ¶ added in v3.44.0 

func WithAutoDeclare() QueryBindConnectorOption

func WithNumericArgs ¶ added in v3.44.0 

func WithNumericArgs() QueryBindConnectorOption

func WithPositionalArgs ¶ added in v3.44.0 

func WithPositionalArgs() QueryBindConnectorOption

func WithTablePathPrefix ¶ added in v3.44.0 

func WithTablePathPrefix(tablePathPrefix string) QueryBindConnectorOption

type QueryMode ¶ added in v3.33.0 

type QueryMode = xsql.QueryMode

type SQLConnector ¶ added in v3.45.0 

type SQLConnector interface {
	driver.Connector

	Close() error
}

func Connector ¶ added in v3.33.0 

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

func MustConnector ¶ added in v3.44.0 

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

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
options
internal
allocator
background
backoff
balancer
balancer/cluster
balancer/config
bind
certificates
clone
closer
cmd/gstack
cmd/gstack/utils
cmd/gtrace
config
conn
coordination
coordination/config
coordination/conversation
Package conversation contains coordination session internal code that helps implement a typical conversation-like session protocol based on a bidirectional gRPC stream.
 Package conversation contains coordination session internal code that helps implement a typical conversation-like session protocol based on a bidirectional gRPC stream.
credentials
decimal
discovery
discovery/config
dsn
empty
endpoint
feature
grpcwrapper/rawoptional
grpcwrapper/rawscheme
grpcwrapper/rawtopic
grpcwrapper/rawtopic/rawtopiccommon
grpcwrapper/rawtopic/rawtopicreader
grpcwrapper/rawtopic/rawtopicreadermock
Code generated by MockGen.
 Code generated by MockGen.
grpcwrapper/rawtopic/rawtopicwriter
grpcwrapper/rawydb
meta
mock
operation
operation/metadata
operation/options
params
pg
pool
query
query/config
query/options
query/result
query/scanner
query/tx
ratelimiter
ratelimiter/config
ratelimiter/errors
ratelimiter/options
repeater
scanner
scheme
scheme/config
scheme/helpers
scripting
scripting/config
secret
session
stack
stats
table
table/config
table/scanner
topic
topic/topicclientinternal
topic/topiclistenerinternal
topic/topicreadercommon
topic/topicreaderinternal
topic/topicwriterinternal
tx
types
value
version
xcontext
xerrors
xiter
xlist
Package xlist is a copy of standard container/list but uses generics for strict checks on compile time
 Package xlist is a copy of standard container/list but uses generics for strict checks on compile time
xrand
xresolver
xslices
xsql
xsql/badconn
xsql/isolation
xstring
xsync
xtest
budget
options
result
result/indexed
result/named
stats
types
topiclistener
topicoptions
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
topicsugar
topictypes
topicwriter

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.