Documentation
¶
Overview ¶
Example (SelectWithParameters) ¶
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
var (
id int32 // required value
myStr string // optional value
)
// Do retry operation on errors with best effort
err = db.Query().Do(ctx, // context manage exiting from Do
func(ctx context.Context, s query.Session) (err error) { // retry operation
_, res, err := s.Execute(ctx,
`SELECT CAST($id AS Uint64) AS id, CAST($myStr AS Text) AS myStr`,
query.WithParameters(
query.Param("$id", query.Uint64Value(123)),
query.Param("$myStr", query.TextValue("test")),
),
)
if err != nil {
return err // for auto-retry with driver
}
defer func() { _ = res.Close() }() // cleanup resources
for res.NextResultSet(ctx) { // iterate over result sets
for res.Next() { // iterate over rows
err = res.ScanNamed(
query.Named("id", &id),
query.Named("myStr", &myStr),
)
if err != nil {
return err // generally scan error not retryable, return it for driver check error
}
}
}
return res.Err() // return finally result error for auto-retry with driver
},
query.WithIdempotent(),
)
if err != nil {
fmt.Printf("unexpected error: %v", err)
}
fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Example (SelectWithoutParameters) ¶
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
var (
id int32 // required value
myStr string // optional value
)
// Do retry operation on errors with best effort
err = db.Query().Do(ctx, // context manage exiting from Do
func(ctx context.Context, s query.Session) (err error) { // retry operation
_, res, err := s.Execute(ctx,
`SELECT 42 as id, "my string" as myStr`,
)
if err != nil {
return err // for auto-retry with driver
}
defer func() { _ = res.Close() }() // cleanup resources
for res.NextResultSet(ctx) { // iterate over result sets
for res.Next() { // iterate over rows
if err = res.Scan(&id, &myStr); err != nil {
return err // generally scan error not retryable, return it for driver check error
}
}
}
return res.Err() // return finally result error for auto-retry with driver
},
query.WithIdempotent(),
)
if err != nil {
fmt.Printf("unexpected error: %v", err)
}
fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Example (TxSelect) ¶
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
var (
id int32 // required value
myStr string // optional value
)
// Do retry operation on errors with best effort
err = db.Query().DoTx(ctx, // context manage exiting from Do
func(ctx context.Context, tx query.TransactionActor) (err error) { // retry operation
res, err := tx.Execute(ctx,
`SELECT 42 as id, "my string" as myStr`,
)
if err != nil {
return err // for auto-retry with driver
}
defer func() { _ = res.Close() }() // cleanup resources
for res.NextResultSet(ctx) { // iterate over result sets
for res.Next() { // iterate over rows
err = res.ScanNamed(
query.Named("id", &id),
query.Named("myStr", &myStr),
)
if err != nil {
return err // generally scan error not retryable, return it for driver check error
}
}
}
return res.Err() // return finally result error for auto-retry with driver
},
query.WithIdempotent(),
query.WithTxSettings(query.TxSettings(
query.WithSnapshotReadOnly(),
)),
)
if err != nil {
fmt.Printf("unexpected error: %v", err)
}
fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Index ¶
- Constants
- func Named(columnName string, destinationValueReference interface{}) (dst namedDestination)
- func NewExecuteOptions(opts ...ExecuteOption) (executeOptions executeOptions)
- func WithIdempotent() idempotentOption
- func WithTxSettings(txSettings *TransactionSettings) txSettingsOption
- type Client
- type ClosableSession
- type DoOption
- type DoOptions
- type DoTxOption
- type DoTxOptions
- type ExecuteOption
- type NamedDestination
- type Operation
- type Parameter
- type Parameters
- type Result
- type Session
- type SessionInfo
- type SessionStatus
- type Transaction
- type TransactionActor
- type TransactionControl
- func DefaultTxControl() *TransactionControl
- func OnlineReadOnlyTxControl(opts ...TxOnlineReadOnlyOption) *TransactionControl
- func SerializableReadWriteTxControl(opts ...TxControlOption) *TransactionControl
- func SnapshotReadOnlyTxControl() *TransactionControl
- func StaleReadOnlyTxControl() *TransactionControl
- func TxControl(opts ...TxControlOption) *TransactionControl
- type TransactionIdentifier
- type TransactionSettings
- type TxControlOption
- type TxExecuteOption
- type TxExecuteOptions
- type TxOnlineReadOnlyOption
- type TxOperation
- type TxOption
- type Type
- type Value
- func BoolValue(v bool) Value
- func BytesValue(v []byte) Value
- func DatetimeValue(v time.Time) Value
- func Int16Value(v int16) Value
- func Int32Value(v int32) Value
- func Int64Value(v int64) Value
- func Int8Value(v int8) Value
- func IntervalValue(v time.Duration) Value
- func TextValue(v string) Value
- func TimestampValue(v time.Time) Value
- func Uint16Value(v uint16) Value
- func Uint32Value(v uint32) Value
- func Uint64Value(v uint64) Value
- func Uint8Value(v uint8) Value
Examples ¶
Constants ¶
const ( SessionStatusUnknown = SessionStatus(iota) SessionStatusReady SessionStatusBusy SessionStatusClosing SessionStatusClosed )
Variables ¶
This section is empty.
Functions ¶
func Named ¶
func Named(columnName string, destinationValueReference interface{}) (dst namedDestination)
func NewExecuteOptions ¶
func NewExecuteOptions(opts ...ExecuteOption) (executeOptions executeOptions)
func WithIdempotent ¶
func WithIdempotent() idempotentOption
func WithTxSettings ¶
func WithTxSettings(txSettings *TransactionSettings) txSettingsOption
Types ¶
type Client ¶
type Client interface {
// Do provide the best effort for execute operation.
//
// Do implements internal busy loop until one of the following conditions is met:
// - deadline was canceled or deadlined
// - retry operation returned nil as error
//
// Warning: if context without deadline or cancellation func than Do can run indefinitely.
Do(ctx context.Context, op Operation, opts ...DoOption) error
// DoTx provide the best effort for execute transaction.
//
// DoTx implements internal busy loop until one of the following conditions is met:
// - deadline was canceled or deadlined
// - retry operation returned nil as error
//
// DoTx makes auto begin (with TxSettings, by default - SerializableReadWrite), commit and
// rollback (on error) of transaction.
//
// If op TxOperation returns nil - transaction will be committed
// If op TxOperation return non nil - transaction will be rollback
// Warning: if context without deadline or cancellation func than DoTx can run indefinitely
DoTx(ctx context.Context, op TxOperation, opts ...DoTxOption) error
}
type ClosableSession ¶
type DoOptions ¶
type DoOptions struct {
Label string
Idempotent bool
RetryOptions []retry.Option
Trace *trace.Query
}
func NewDoOptions ¶
type DoTxOption ¶
type DoTxOption interface {
// contains filtered or unexported methods
}
type DoTxOptions ¶
type DoTxOptions struct {
DoOptions
TxSettings *TransactionSettings
}
func NewDoTxOptions ¶
func NewDoTxOptions(opts ...DoTxOption) (doTxOptions DoTxOptions)
type ExecuteOption ¶
type ExecuteOption interface {
// contains filtered or unexported methods
}
type NamedDestination ¶ added in v3.73.0
type NamedDestination interface {
Name() string
Destination() interface{}
}
type Operation ¶
Operation is the interface that holds an operation for retry. if Operation returns not nil - operation will retry if Operation returns nil - retry loop will break
type Parameters ¶
type Parameters struct {
// contains filtered or unexported fields
}
Parameters
func WithParameters ¶
func WithParameters(params ...Parameter) *Parameters
func (*Parameters) Add ¶
func (params *Parameters) Add(parameters ...Parameter)
func (*Parameters) Count ¶
func (params *Parameters) Count() int
func (*Parameters) Each ¶
func (params *Parameters) Each(it func(name string, v Value))
func (*Parameters) Params ¶
func (params *Parameters) Params() queryParams
func (*Parameters) String ¶
func (params *Parameters) String() string
type Session ¶
type Session interface {
SessionInfo
// Execute executes query.
//
// Execute used by default:
// - DefaultTxControl
// - flag WithKeepInCache(true) if params is not empty.
Execute(ctx context.Context, query string, opts ...ExecuteOption) (txr Transaction, r Result, err error)
Begin(ctx context.Context, txSettings *TransactionSettings) (Transaction, error)
}
type SessionInfo ¶
type SessionInfo interface {
ID() string
NodeID() int64
Status() SessionStatus
LastUsage() time.Time
}
type SessionStatus ¶
type SessionStatus uint32
func (SessionStatus) String ¶
func (s SessionStatus) String() string
type Transaction ¶
type TransactionActor ¶ added in v3.101.3
type TransactionControl ¶
type TransactionControl struct {
// contains filtered or unexported fields
}
func DefaultTxControl ¶
func DefaultTxControl() *TransactionControl
DefaultTxControl returns default transaction control with serializable read-write isolation mode and auto-commit
func OnlineReadOnlyTxControl ¶
func OnlineReadOnlyTxControl(opts ...TxOnlineReadOnlyOption) *TransactionControl
OnlineReadOnlyTxControl returns online read-only transaction control
func SerializableReadWriteTxControl ¶
func SerializableReadWriteTxControl(opts ...TxControlOption) *TransactionControl
SerializableReadWriteTxControl returns transaction control with serializable read-write isolation mode
func SnapshotReadOnlyTxControl ¶
func SnapshotReadOnlyTxControl() *TransactionControl
SnapshotReadOnlyTxControl returns snapshot read-only transaction control
func StaleReadOnlyTxControl ¶
func StaleReadOnlyTxControl() *TransactionControl
StaleReadOnlyTxControl returns stale read-only transaction control
func TxControl ¶
func TxControl(opts ...TxControlOption) *TransactionControl
TxControl makes transaction control from given options
func (*TransactionControl) Desc ¶
func (t *TransactionControl) Desc() *Ydb_Query.TransactionControl
type TransactionIdentifier ¶
type TransactionIdentifier interface {
ID() string
}
type TransactionSettings ¶
type TransactionSettings struct {
// contains filtered or unexported fields
}
Transaction control options
func TxSettings ¶
func TxSettings(opts ...TxOption) *TransactionSettings
TxSettings returns transaction settings
func (*TransactionSettings) Desc ¶
func (txSettings *TransactionSettings) Desc() *Ydb_Query.TransactionSettings
type TxControlOption ¶
type TxControlOption func(*txControlDesc)
func BeginTx ¶
func BeginTx(opts ...TxOption) TxControlOption
BeginTx returns begin transaction control option
func WithTx ¶
func WithTx(t TransactionIdentifier) TxControlOption
func WithTxID ¶
func WithTxID(txID string) TxControlOption
type TxExecuteOption ¶
type TxExecuteOption interface {
// contains filtered or unexported methods
}
type TxExecuteOptions ¶
type TxExecuteOptions struct {
// contains filtered or unexported fields
}
func NewTxExecuteOptions ¶
func NewTxExecuteOptions(opts ...TxExecuteOption) (txExecuteOptions TxExecuteOptions)
type TxOnlineReadOnlyOption ¶
type TxOnlineReadOnlyOption func(*txOnlineReadOnly)
func WithInconsistentReads ¶
func WithInconsistentReads() TxOnlineReadOnlyOption
type TxOperation ¶
type TxOperation func(ctx context.Context, tx TransactionActor) error
TxOperation is the interface that holds an operation for retry. if TxOperation returns not nil - operation will retry if TxOperation returns nil - retry loop will break
type TxOption ¶
type TxOption func(*TransactionSettings)
Transaction control options
func WithDefaultTxMode ¶
func WithDefaultTxMode() TxOption
func WithOnlineReadOnly ¶
func WithOnlineReadOnly(opts ...TxOnlineReadOnlyOption) TxOption
func WithSerializableReadWrite ¶
func WithSerializableReadWrite() TxOption
func WithSnapshotReadOnly ¶
func WithSnapshotReadOnly() TxOption
func WithStaleReadOnly ¶
func WithStaleReadOnly() TxOption